Обзор

Введение

Интеграции

Библиотеки (SDK)

Руководство пользователя

Справочник API

Вебхуки

Отправка писем через HTTP API

Отправить единичное письмо #

post

/email

Отправка отдельных писем через Haskimail так же проста, как отправка HTTP POST-запроса к нашему эндпоинту /email c JSON-сообщением в теле запроса.

Пример запроса с помощью 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": "Привет дорогой пользователь Хаски",
  "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 token

Формат JSON-сообщения

JSON-сообщения передаются в теле HTTP POST-запроса. Поля From и To могут принимать имя в формате Иван Иванов <email@example.com>. Вы можете указать HtmlBody для сообщений в формате HTML, TextBody для простого текста или включить оба для создания многокомпонентного сообщения. Многокомпонентный формат отправляет HTML с текстовой версией для клиентов, которые не поддерживают HTML. Передача заголовков необязательна.

У вас должна быть зарегистрирована и подтверждена подпись отправителя с адресом электронной почты отправителя. В противном случае вы получите ответ HTTP 422 (Unprocessable Entity).

Имя в подписи отправителя можно переопределить через API. Это полезно, если вы хотите использовать информацию об участнике в электронном письме, сохраняя при этом свой адрес электронной почты отправителя. Просто передайте имя в поле 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>"

"Headers": [{"Name":"Message-ID", "Value": "<my-id-123@example.com>"}]

Если идентификатор канала сообщений не указан, по умолчанию будет использоваться идентификатор канала для исходящих сообщений (канал транзакционных сообщений по умолчанию — Default Transactional Stream).

Максимальная длина темы письма — 2000 символов, а максимальная длина адреса отправителя ("From") — 255 символов. Длина рассчитывается по количеству кодовых точек UTF-16: кодовые точки Unicode в диапазоне 0000 - FFFF считаются как 1, а кодовые точки Unicode выше FFFF — как 2.

Пример формата JSON-сообщения

{
  "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"
}

Отслеживание открытий

Существует два способа активировать отслеживание открытий для ваших писем:

Пример запроса API с отслеживанием открытий

{
  ...
  "TrackOpens" : true
}

Отслеживание ссылок

Вы можете включить отслеживание ссылок, чтобы получать информацию о ссылках, по которым переходят получатели ваших писем. Отслеживание ссылок можно включить для каждого отдельного письма или для всего сервера.

Узнать больше об отслеживании ссылок..

Пример API-запроса с отслеживанием ссылок

{
  ...
  "TrackLinks" : "HtmlAndText"
}

Вложения

Вложения указываются в массиве Attachments в JSON-сообщении. Каждое вложение представлено отдельным объектом внутри этого массива.

Поле Name содержит имя файла, которое будет отображаться получателю сообщения. Во избежание распространения вирусов и шпионских программ мы запрещаем определенные типы файлов:

Запрещенные типы файлов: vbs, exe, bin, bat, chm, com, cpl, crt, hlp, hta, inf, ins, isp, jse, lnk, mdb, pcd, pif, reg, scr, sct, shs, vbe, vba, wsf, wsh, wsl, msc, msi, msp, mst.

Поле ContentType указывает MIME-тип контента, который почтовые клиенты используют для интерпретации вложения.

Поле Content хранит двоичные данные файла, которые должны быть переданы в виде строки, закодированной в формате base64. Большинство языков программирования и библиотек имеют встроенные функции для кодирования в base64, например, Java, .NET, PHP, Ruby

Ограничения:

Если обнаружен тип файла с запрещенным расширением, сообщение будет отклонено. При использовании SMTP вы получите сообщение об ошибке SMTP API.
Сообщения имеют ограничения по размеру, превышение которых приведет к отклонению сообщения:
- TextBody и HtmlBody могут иметь размер до 5 МБ каждый.
- Общий размер сообщения, включая вложения, может составлять до 10 МБ. Это может быть одно вложение или несколько вложений, общий размер которых не превышает 10 МБ. Обратите внимание: строки, закодированные в Base64, могут выглядеть больше, чем есть на самом деле, но Haskimail рассчитывает размер вложения после кодирования в Base64.
Мы рекомендуем отправлять письма с вложениями из фонового процесса, а не в ответ на действие пользователя в том же обработчике веб-запросов. Это связано с тем, что отправка сообщений большего размера на серверы Haskimail занимает больше времени. Ваши пользователи будут вам за это благодарны!

Пример сообщения с вложениями:

{
  ...
  "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"
    }
  ]
}

HTML-код с примером встраивания изображения:

<img src="cid:part1.01030607.06070005@gmail.com">

Успех

В случае успеха вы получите JSON-сообщение, подобное приведенному в примере.

Поле MessageID ожно использовать для ведения журнала в вашей системе. Его можно использовать для сопоставления отправленного вами сообщения с возможным отклонением, полученным от вебхука для отклоненных сообщений или API отклоненных сообщений.

Полный список ошибок API.

Пример JSON-ответа:

{
  "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 не хранит вложения.

Отправка пакетов писем #

post

/email/batch

Мы понимаем, что разработчикам с большими объемами отправки или ограничениями по времени обработки необходимо отправлять сообщения пакетами. Для этого мы предоставляем конечную точку пакетной отправки, которая позволяет отправлять до 500 правильно сформированных сообщений Haskimail за один API-вызов. Если вы отправляете массовые рассылки с помощью пакетного вызова, используйте поле MessageStream, чтобы указать канал отправки.

Обратите внимание, что конечная точка пакетной отправки принимает до 500 сообщений на один API-вызов и до 50 МБ размера полезной нагрузки, включая вложения.

Формат пакетного сообщения — это массив JSON, содержащий несколько запросов на отправку сообщений.

Примеры пакетных запросов можно увидеть здесь.

Пример запроса с curl

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 смотрите здесь.

Пример JSON-ответа

[
  {
    "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"
  }
]