Если вы хотите отправлять письма через ваше приложение, вам нужно будет выполнить несколько шагов.
* **Шаг 1:** Решите, хотите ли вы использовать наш API или SMTP
* **Шаг 2:** Настройте адреса или домены, с которых вы будете отправлять письма.
* **Шаг 3:** Настройте каналы отправки для различных типов писем, которые будете отправлять.
* **Шаг 4:** Отправьте тестовое письмо.
* **Шаг 5:** Интегрируйте с вашим приложением.
* **Шаг 6:** Используйте дополнительные возможности для оптимизации отправки: вебхуки и шаблоны.
## **Шаг 1: Решите, использовать ли API или SMTP**
Первое, что вам нужно решить перед интеграцией с Haskimail — это использовать API или SMTP. Оба метода позволят вам отправлять письма, но каждый из них имеет свои плюсы и минусы. Вот таблица, которая поможет вам выбрать подходящий метод:
## **Шаг 2: Настройка адресов для отправки**
После [создания аккаунта](https://lk.haskimail.ru/registration.php) мы автоматически создадим ваш первый сервер. Серверы помогают организовывать отправку писем по проектам, клиентам или окружениям, аналогично папкам на вашем компьютере. Каналы отправки помогают разделять различные типы сообщений, которые вы отправляете.\
\
Каждый сервер имеет свой API-токен для отправки писем и API-запросов. Также сервер будет иметь свои настройки отслеживания открытий и ссылок.\
\
В рамках каждого сервера можно разделить трафик транзакционных и маркетинговых писем, используя каналы отправки. Транзакционные каналы отправки используются для уникальных писем, которые триггерятся действиями пользователя, например, для письма с приветствием, сброса пароля или квитанций. Маркетинговые каналы отправки — для массовых сообщений, отправляемых множеству получателей, таких как анонсы, рассылки или другие письма от вашего приложения.\
\
Теперь вы готовы настроить адреса, с которых будете отправлять письма. Для этого есть два способа:
* Добавить обратный адрес для рассылки с конкретного адреса.
* Настроить весь домен отправки.
Мы используем подписи отправителей и проверку доменов, чтобы убедиться, что вы являетесь владельцем почтовых ящиков, с которых хотите отправлять письма. Это помогает предотвратить спам и злоупотребления. Эти меры безопасности помогают нам поддерживать отличную репутацию у ISP и обеспечивать доставку ваших писем в папку «Входящие» быстро и надежно. Вы можете добавлять столько подписей отправителей и проверенных доменов, сколько вам нужно, ограничений нет.
## **Добавление обратного адреса отправителя**
Если вы проходите процесс первоначальной настройки, вам будет предложено создать обратный адрес отправителя сразу после создания аккаунта. После этого вы можете кликнуть на «Подтвердить обратный адрес» и добавить новую почту.
Выберите **Подтвердить обратный адрес** и заполните данные для email-адреса «От кого»).
## **Настройка домена**
Настройка домена позволит вам отправлять письма с любого email-адреса в рамках одного домена. Например, после проверки домена [mydomain.ru](http://mydomain.ru) вы сможете отправлять письма с любого адреса вида [someone@mydomain.ru](mailto:someone@mydomain.ru) через платформу Haskimail.\
\
**Чтобы проверить домен, выполните следующие шаги:**
1. Войдите в Haskimail и перейдите в раздел «Домены и отправители».
1. Нажмите **Добавить домен** и введите домен.
2. Сгенерируйте записи DKIM и SPF для этого домена и добавьте их в ваш DNS.
1. Подтверждение может занять до 48 часов.
## **Шаг 3: Настройка каналов отправки**
Давайте разберемся, почему каналы отправки важны и как их создавать и использовать. Мы настоятельно рекомендуем создавать каналы для всех типов сообщений, которые вы отправляете. Это даст вам гораздо лучшее понимание того, как работает каждый тип сообщений, поскольку все статистические данные и уведомления для каждого канала будут разделены.\
\
Это также полезный подход в случае отписки получателей. Например, если получатель решит отписаться от канала для рассылок, это не повлияет на его способность получать обновления, такие как изменения в условиях использования, с другого канала.\
\
Другой важный момент — это использование поддомена для ваших массовых рассылок. Мы рекомендуем отправлять высокоэффективные транзакционные письма с основного домена, а для всех маркетинговых и массовых рассылок использовать поддомен. Это соответствует лучшим практикам по разделению репутации email-каналов, рекомендованным такими провайдерами, как [Mail.ru](http://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": "Hello dear HaskiMail user."
}'
```
## **Шаг 5: Интеграция с вашим приложением**
Теперь, когда вы отправили тестовое письмо, пора интегрировать Haskimail с вашим приложением. Это потребует некоторых технических навыков и выходит за рамки этого руководства. Однако для подробных инструкций посетите наш раздел документации для разработчиков по API и SMTP.
* [Официальные библиотеки Haskimail](https://haskimail.ru/developer/integration/official-libraries)
* [Неофициальные библиотеки Haskimail](https://haskimail.ru/developer/integration/community-libraries)
## **Шаг 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": ""
}
```
С помощью полученных данных JSON вы можете быстро найти письмо, вызвавшее уведомление (по полю **MessageID**), проверить, можно ли реактивировать получателя (по полю **CanActivate**), а также получить подробности о причине возврата через поля **Description** и **Details**. Поле **From** позволяет быстро определить отправителя.\
\
Пример использования:
* Оповещение отправителя о возврате письма.
* Маркировка пользователя или адреса как возвратившегося с возможностью реактивации через [API](https://haskimail.ru/developer/api/bounce-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": ""
}
```