Отправка писем через ваше приложение
Теперь, когда мы рассмотрели различные сценарии, для которых может быть полезен HaskiMail, давайте перейдем к деталям.
Если вы хотите отправлять письма через ваше приложение, вам нужно будет выполнить несколько шагов.
- Шаг 1: Решите, хотите ли вы использовать наш API или SMTP
- Шаг 2: Настройте адреса или домены, с которых вы будете отправлять письма.
- Шаг 3: Настройте каналы отправки для различных типов писем, которые будете отправлять.
- Шаг 4: Отправьте тестовое письмо.
- Шаг 5: Интегрируйте с вашим приложением.
- Шаг 6: Используйте дополнительные возможности для оптимизации отправки: вебхуки и шаблоны.
Шаг 1: Решите, использовать ли API или SMTP
Первое, что вам нужно решить перед интеграцией с HaskiMail — это использовать API или SMTP. Оба метода позволят вам
отправлять письма, но каждый из них имеет свои плюсы и минусы. Вот таблица, которая поможет вам выбрать подходящий
метод:
Шаг 2: Настройка адресов для отправки
После создания аккаунта мы автоматически создадим ваш первый сервер. Серверы помогают организовывать отправку писем
по проектам, клиентам или окружениям, аналогично папкам на вашем компьютере. Каналы отправки помогают разделять
различные типы сообщений, которые вы отправляете.
Каждый сервер имеет свой API-токен для отправки писем и API-запросов. Также сервер будет иметь свои настройки
отслеживания открытий и ссылок.
В рамках каждого сервера можно разделить трафик транзакционных и маркетинговых писем, используя каналы отправки.
Транзакционные каналы отправки используются для уникальных писем, которые триггерятся действиями пользователя,
например, для письма с приветствием, сброса пароля или квитанций. Маркетинговые каналы отправки — для массовых
сообщений, отправляемых множеству получателей, таких как анонсы, рассылки или другие письма от вашего
приложения.
Теперь вы готовы настроить адреса, с которых будете отправлять письма. Для этого есть два способа:
- Добавить обратный адрес для рассылки с конкретного адреса.
- Настроить весь домен отправки.
Мы используем подписи отправителей и проверку доменов, чтобы убедиться, что вы являетесь владельцем почтовых ящиков,
с которых хотите отправлять письма. Это помогает предотвратить спам и злоупотребления. Эти меры безопасности
помогают нам поддерживать отличную репутацию у ISP и обеспечивать доставку ваших писем в папку «Входящие» быстро
и надежно. Вы можете добавлять столько подписей отправителей и проверенных доменов, сколько вам нужно, ограничений нет.
Добавление обратного адреса отправителя
Если вы проходите процесс первоначальной настройки, вам будет предложено создать обратный адрес отправителя сразу после
создания аккаунта. После этого вы можете кликнуть на «Подтвердить обратный адрес» и добавить новую почту.
Выберите Подтвердить обратный адрес и заполните данные для email-адреса «От кого»).
Настройка домена
Настройка домена позволит вам отправлять письма с любого email-адреса в рамках одного домена. Например, после проверки
домена mydomain.ru вы сможете отправлять письма с любого адреса вида someone@mydomain.ru через платформу HaskiMail.
Чтобы проверить домен, выполните следующие шаги:
1. Войдите в HaskiMail и перейдите в раздел «Домены и отправители».
2. Нажмите Добавить домен и введите домен.
3. Сгенерируйте записи DKIM и SPF для этого домена и добавьте их в ваш DNS.
4. Подтверждение может занять до 48 часов.
Шаг 3: Настройка каналов отправки
Давайте разберемся, почему каналы отправки важны и как их создавать и использовать. Мы настоятельно рекомендуем
создавать каналы для всех типов сообщений, которые вы отправляете. Это даст вам гораздо лучшее понимание того,
как работает каждый тип сообщений, поскольку все статистические данные и уведомления для каждого канала будут
разделены.
Это также полезный подход в случае отписки получателей. Например, если получатель решит отписаться от канала для
рассылок, это не повлияет на его способность получать обновления, такие как изменения в условиях использования,
с другого канала.
Другой важный момент — это использование поддомена для ваших массовых рассылок. Мы рекомендуем отправлять
высокоэффективные транзакционные письма с основного домена, а для всех маркетинговых и массовых рассылок
использовать поддомен. Это соответствует лучшим практикам по разделению репутации email-каналов, рекомендованным такими
провайдерами, как Mail.ru.
Таким образом, ваши транзакционные сообщения не будут зависеть от доставляемости и вовлеченности массовых рассылок, и
наоборот. Если не разделять эти репутации, низкая или отрицательная вовлеченность от массовых рассылок может повлиять
на доставляемость важных транзакционных сообщений.
Отправка через канал немного отличается в зависимости от метода отправки (API или SMTP).
Шаг 4: Отправка тестового письма
Теперь, когда у вас есть подтвержденная подпись отправителя (и, возможно, проверенный домен), давайте отправим тестовое
письмо. Существует несколько способов отправки тестового письма:
- Postman
- cURL: Вы можете отправить тестовое письмо через терминал, используя cURL:
curl "https://api.haskimail.ru/email" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-HaskiMail-Server-Token: server token" \
-d '{
"From": "sender@example.com",
"To": "receiver@example.com",
"Subject": "HaskiMail test",
"TextBody": "Hello dear HaskiMail user.",
"HtmlBody": "<html><body><strong>Hello</strong> dear HaskiMail user.</body></html>"
}'
Шаг 5: Интеграция с вашим приложением
Теперь, когда вы отправили тестовое письмо, пора интегрировать HaskiMail с вашим приложением. Это потребует некоторых
технических навыков и выходит за рамки этого руководства. Однако для подробных инструкций посетите наш раздел
документации для разработчиков по API и SMTP.
- Официальные библиотеки Haskimail
- Неофициальные библиотеки Haskimail
Шаг 6: Использование дополнительных возможностей
После того как вы настроили приложение и начали отправлять письма, вы можете использовать дополнительные функции
HaskiMail, такие как вебхуки и шаблоны.
Вебхуки
HaskiMail предоставляет вебхуки для уведомлений о возвратах, кликах и отслеживании открытия сообщений. Вебхуки
передаются в виде HTTP POST-запросов с форматированным JSON на URL, указанный в настройках вашего сервера
HaskiMail. С помощью этих вебхуков вы можете получать уведомления и данные в реальном времени, по мере наступления
событий, без необходимости делать дополнительные запросы к API для проверки новых событий.
Вы можете использовать вебхуки HaskiMail для множества целей, например:
- Получать уведомления, когда письмо было доставлено и/или открыто.
- Получать уведомления о кликах по ссылкам в письмах.
- Получать уведомления в реальном времени о возвратах (bounces) и жалобах на спам.
Уведомления о возвратах и жалобах на спам
Используя вебхук для возвратов, вы будете получать POST-запросы на ваш URL всякий раз, когда происходит возврат. Пример
формата уведомлений о возврате и жалобах на спам:
{
"RecordType": "Bounce",
"ID": 4323372036854775807,
"Type": "HardBounce",
"TypeCode": 1,
"Name": "Hard bounce",
"Tag": "Test",
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"ServerID": 23,
"Description": "The server was unable to deliver your message (ex: unknown user, mailbox not found).",
"Details": "Test bounce details",
"Email": "john@example.com",
"From": "sender@example.com",
"BouncedAt": "2019-11-05T16:33:54.9070259Z",
"DumpAvailable": true,
"Inactive": true,
"CanActivate": true,
"Subject": "Test subject",
"Content": "<Full dump of bounce>"
}
С помощью полученных данных JSON вы можете быстро найти письмо, вызвавшее уведомление (по полю MessageID), проверить,
можно ли реактивировать получателя (по полю CanActivate), а также получить подробности о причине возврата через поля
Description и Details. Поле From позволяет быстро определить отправителя.
Пример использования:
- Оповещение отправителя о возврате письма.
- Маркировка пользователя или адреса как возвратившегося с возможностью реактивации через API.
Отслеживание доставки
Когда HaskiMail получает успешный отклик от почтового сервера получателя, письмо считается доставленным. Важно помнить,
что это не означает, что письмо уже попало в почтовый ящик получателя. Дополнительная обработка письма может
происходить на сервере получателя. Вебхуки для отслеживания доставки позволяют получать уведомления, когда
письмо было принято сервером, а также его детали.
Пример уведомления о доставке:
{
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Recipient": "john@example.com",
"DeliveredAt": "2019-11-05T16:33:54.9070259Z",
"Details": "Test delivery webhook details",
"Tag": "welcome-email",
"ServerId": 23,
"Metadata" : {
"a_key" : "a_value",
"b_key": "b_value"
},
"RecordType": "Delivery"
}
Используйте данные для обновления вашего приложения или базы данных о статусе доставки, а также для информирования
клиентов.
Отслеживание открытия писем
Вебхук для отслеживания открытия уведомляет вас, когда письмо было открыто. В уведомлении содержатся данные о клиенте,
операционной системе и местоположении получателя, который открыл письмо. Отслеживание открытий работает только для
HTML-писем.
Пример уведомления о первом открытии письма:
{
"RecordType": "Open",
"FirstOpen": true,
"Client": {
"Name": "Chrome 35.0.1916.153",
"Company": "Google",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X 10"
},
"Platform": "WebMail",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "188.2.95.4"
},
"MessageID": "883953f4-6105-42a2-a16a-77a8eac79483",
"Metadata": {
"a_key": "a_value",
"b_key": "b_value"
},
"ReceivedAt": "2019-11-05T16:33:54.9070259Z",
"Tag": "welcome-email",
"Recipient": "john@example.com"
}
Отслеживание кликов
Этот вебхук отправляет уведомления, когда ссылка в письме была нажата. В уведомлении содержится информация
о местоположении получателя, URL, который был кликом, а также почтовый клиент и операционная система. Этот
вебхук может быть включен как для HTML, так и для текстовых писем.
Пример уведомления о клике по ссылке:
{
"RecordType": "Click",
"ClickLocation": "HTML",
"Client": {
"Name": "Chrome 35.0.1916.153",
"Company": "Google",
"Family": "Chrome"
},
"OS": {
"Name": "OS X 10.7 Lion",
"Company": "Apple Computer, Inc.",
"Family": "OS X 10"
},
"Platform": "Desktop",
"UserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_7_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/35.0.1916.153 Safari/537.36",
"OriginalLink": "https://example.com",
"Geo": {
"CountryISOCode": "RS",
"Country": "Serbia",
"RegionISOCode": "VO",
"Region": "Autonomna Pokrajina Vojvodina",
"City": "Novi Sad",
"Zip": "21000",
"Coords": "45.2517,19.8369",
"IP": "8.8.8.8"
},
"MessageID": "00000000-0000-0000-0000-000000000000",
"Metadata": {
"a_key": "a_value",
"b_key": "b_value"
},
"ReceivedAt": "2017-10-25T15:21:11.9065619Z",
"Tag": "welcome-email",
"Recipient": "john@example.com"
}
Жалоба на спам
Вебхук для жалоб на спам уведомит вас, когда получатель вручную пометит ваше письмо как спам. Это полезно для того,
чтобы оперативно реагировать на жалобы и предотвращать дальнейшие проблемы с доставкой.
Пример уведомления о жалобе на спам:
{
"RecordType": "SpamComplaint",
"ID": 42,
"Type": "SpamComplaint",
"TypeCode": 512,
"Name": "Spam complaint",
"Tag": "Test",
"MessageID": "00000000-0000-0000-0000-000000000000",
"Metadata": {
"a_key": "a_value",
"b_key": "b_value"
},
"ServerID": 1234,
"Description": "",
"Details": "Test spam complaint details",
"Email": "john@example.com",
"From": "sender@example.com",
"BouncedAt": "2019-11-05T16:33:54.9070259Z",
"DumpAvailable": true,
"Inactive": true,
"CanActivate": false,
"Subject": "Test subject"
"Content": "<Abuse report dump>"
}
