Теги и метаданные помогают связать письмо с данными вашего приложения: понять, какой это тип письма, к какому заказу или пользователю оно относится.
Теги
Тег — одна текстовая метка письма, например welcome, password-reset или order. У письма может быть только один тег длиной до 1000 символов.
По тегам удобно:
- смотреть статистику отдельно по каждому типу писем — на вкладке Статистика канала есть фильтр по тегам;
- фильтровать письма, открытия, клики и возвраты в API;
- отличать события в вебхуках: тег приходит в поле
campaign_id.
Как задать тег
Через API — полем Tag:
{
"From": "shop@example.ru",
"To": "ivan@example.com",
"Subject": "Ваш заказ оформлен",
"TextBody": "Спасибо за заказ!",
"Tag": "order"
}
Через SMTP — заголовком X-HM-Tag:
X-HM-Tag: order
Метаданные
Метаданные — произвольные пары «ключ — значение», которые вы прикрепляете к письму: ID заказа, ID пользователя, номер тикета. Haskimail их не показывает получателю, а возвращает вам в вебхуках в поле custom_vars (строка с JSON). Так событие доставки или возврата сразу связывается с объектом в вашей системе — без поиска по MessageID.
Через API — полем Metadata:
{
"From": "shop@example.ru",
"To": "ivan@example.com",
"Subject": "Ваш заказ оформлен",
"TextBody": "Спасибо за заказ!",
"Tag": "order",
"Metadata": { "order_id": "1042", "user_id": "48213" }
}
Через SMTP — заголовком X-HM-Metadata. Формат заголовка описан в документации по SMTP.
Советы
- Используйте небольшой набор постоянных тегов по типам писем, а не уникальный тег на каждое письмо: иначе фильтр статистики станет бесполезным.
- Уникальные значения — номер заказа, ID пользователя — передавайте в метаданных.
- Не кладите в теги и метаданные персональные данные и секреты: пароли, токены, номера карт.
Подробнее о полях запроса — в документации по отправке через API.