Отправка отдельных писем через Haskimail так же проста, как отправка HTTP POST-запроса к нашему эндпоинту /email c JSON-сообщением в теле запроса.
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": "Привет дорогой пользователь Хаски",
"HtmlBody": "<html><body><strong>Привет</strong> дорогой пользователь Хаски.</body></html>",
"MessageStream": "outbound"
}'Для аутентификации в сервисе необходимо использовать заголовок X-Haskimail-Server-Token. У каждого сервера Haskimail есть свой собственный API-токен, что позволяет изолировать доступ и данные для каждого приложения, подключающегося к Haskimail.
Название заголовка и его значение нечувствительны к регистру. Если вы выполните запрос с неправильными или отсутствующими заголовками, вы получите ответ HTTP 401 (Ошибка авторизации).
Для целей тестирования Haskimail позволяет отправлять тестовые письма, которые фактически не будут доставлены получателю. Этот метод обычно используется для проверки корректности ваших данных. Вы можете сделать это, передав HASKIMAIL_API_TEST в качестве API-токена сервера.
X-Haskimail-Server-Token: server tokenJSON-сообщения передаются в теле HTTP POST-запроса. Поля From и To могут принимать имя в формате Иван Иванов <email@example.com>. Вы можете указать HtmlBody для сообщений в формате HTML, TextBody для простого текста или включить оба для создания многокомпонентного сообщения. Многокомпонентный формат отправляет HTML с текстовой версией для клиентов, которые не поддерживают HTML. Передача заголовков необязательна.
From, "From": "John Smith <sender@example.com>". Это также относится к полям To, Cc, and Bcc.
To, Cc, and Bcc fields. Несколько адресов разделяются запятыми. Максимальное количество получателей на сообщение - 50. Это означает, что общее количество получателей (To, Cc, and Bcc) не должно превышать 50.Tag. Это позволяет получать подробную статистику по всем письмам с тегами. Для каждого сообщения можно использовать только один тег. Максимальный размер тега — 1000 символов.Metadata."To" : "\"Иван Иванов, маркетолог.\" <receiver@example.com>"{
"From": "sender@example.com",
"To": "receiver@example.com",
"Cc": "copied@example.com",
"Bcc": "blank-copied@example.com",
"Subject": "Тест",
"Tag": "Приглашение",
"HtmlBody": "<b>Привет</b>",
"TextBody": "Привет",
"ReplyTo": "reply@example.com",
"Metadata": {
"Color":"blue",
"Client-Id":"12345"
},
"Headers": [
{
"Name": "CUSTOM-HEADER",
"Value": "value"
}
],
"TrackOpens": true,
"TrackLinks": "HtmlOnly",
"MessageStream": "outbound"
}Существует два способа активировать отслеживание открытий для ваших писем:
{
...
"TrackOpens" : true
}Вы можете включить отслеживание ссылок, чтобы получать информацию о ссылках, по которым переходят получатели ваших писем. Отслеживание ссылок можно включить для каждого отдельного письма или для всего сервера.
{
...
"TrackLinks" : "HtmlAndText"
}Вложения указываются в массиве Attachments в JSON-сообщении. Каждое вложение представлено отдельным объектом внутри этого массива.
Поле Name содержит имя файла, которое будет отображаться получателю сообщения. Во избежание распространения вирусов и шпионских программ мы запрещаем определенные типы файлов:
Поле ContentType указывает MIME-тип контента, который почтовые клиенты используют для интерпретации вложения.
Поле Content хранит двоичные данные файла, которые должны быть переданы в виде строки, закодированной в формате base64. Большинство языков программирования и библиотек имеют встроенные функции для кодирования в base64, например, Java, .NET, PHP, Ruby
Ограничения:
TextBody и HtmlBody могут иметь размер до 5 МБ каждый.{
...
"Attachments": [
{
"Name": "readme.txt",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "text/plain"
},
{
"Name": "report.pdf",
"Content": "dGVzdCBjb250ZW50",
"ContentType": "application/octet-stream"
}
]
}Haskimail также позволяет отправлять изображения, встраиваемые в HTML-сообщения. Изображения должны быть закодированы в формате base64, а поле ContentID должно соответствовать CID изображения.
Haskimail автоматически встроит изображения в HTML-код, если CID-теги совпадают. ПРИМЕЧАНИЕ: Если вы ссылаетесь на вложенное изображение несколько раз в вашем сообщении, достаточно вложить изображение только один раз. Haskimail будет использовать изображение столько раз, сколько на него ссылаются в вашем HTML-коде. Это сэкономит трафик и позволит эффективнее использовать ограничение на размер вложений.
{
...
"Attachments": [
{
"Name": "bacon.jpg",
"Content": "/9j/4AAQSkZJRgABAgEAAAAAAAD/4",
"ContentType": "image/jpeg",
"ContentID": "cid:part1.01030607.06070005@gmail.com"
}
]
}<img src="cid:part1.01030607.06070005@gmail.com">В случае успеха вы получите JSON-сообщение, подобное приведенному в примере.
Поле MessageID ожно использовать для ведения журнала в вашей системе. Его можно использовать для сопоставления отправленного вами сообщения с возможным отклонением, полученным от вебхука для отклоненных сообщений или API отклоненных сообщений.
Полный список ошибок API.
{
"ErrorCode": 0,
"Message": "OK",
"MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
"SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
"To": "receiver@example.com"
}Вложения невозможно получить через пользовательский интерфейс, API или вебхуки Haskimail, так как Haskimail не хранит вложения.
Мы понимаем, что разработчикам с большими объемами отправки или ограничениями по времени обработки необходимо отправлять сообщения пакетами. Для этого мы предоставляем конечную точку пакетной отправки, которая позволяет отправлять до 500 правильно сформированных сообщений Haskimail за один API-вызов. Если вы отправляете массовые рассылки с помощью пакетного вызова, используйте поле MessageStream, чтобы указать канал отправки.
Обратите внимание, что конечная точка пакетной отправки принимает до 500 сообщений на один API-вызов и до 50 МБ размера полезной нагрузки, включая вложения.
Формат пакетного сообщения — это массив JSON, содержащий несколько запросов на отправку сообщений.
Примеры пакетных запросов можно увидеть здесь.
curl "https://api.haskimail.ru/email/batch" \
-X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "X-Haskimail-Server-Token: server token" \
-d '[{
"From": "sender@example.com",
"To": "receiver1@example.com",
"Subject": "Haskimail тест #1",
"TextBody": "Привет, дорогой пользователь Хаски",
"HtmlBody": "<html><body><strong>Привет</strong> дорогой пользователь Хаски</body></html>",
"MessageStream": "outbound"
},
{
"From": "sender@example.com",
"To": "receiver2@example.com",
"Subject": "Тестовое письмо Haskimail №2",
"TextBody": "Здравствуйте, уважаемый пользователь Haskimail.",
"HtmlBody": "<html><body><strong>Здравствуйте</strong> уважаемый пользователь Haskimail.</body></html>",
"MessageStream": "outbound"
}
]'Аналогично, вы получите соответствующий массив JSON, содержащий ответ для каждого сообщения, отправленного в вашем пакетном вызове.
Полный список ошибок API смотрите здесь.
[
{
"ErrorCode": 0,
"Message": "OK",
"MessageID": "b7bc2f4a-e38e-4336-af7d-e6c392c2f817",
"SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
"To": "receiver1@example.com"
},
{
"ErrorCode": 0,
"Message": "OK",
"MessageID": "e2ecbbfc-fe12-463d-b933-9fe22915106d",
"SubmittedAt": "2010-11-26T12:01:05.1794748-05:00",
"To": "receiver2@example.com"
}
]