Перейти к содержанию

EMAIL

Отправка

Для отправки EMAIL-сообщения необходимо создать домен отправителя рассылки. Это можно сделать:

После того как домен будет подтвержен можно использовать метод POST /email/messages, передавая в теле параметры сообщения с указанием данных авторизации в заголовке.

Параметры запроса

Параметр Тип данных Описание и Допустимые значения
Recipients array[object] Данные получателя
СheckUnsubscription booolean Проверка на наличие отписок у получателей сообщения:
- По умолчанию поле имеет значение false.
- Если придет значение true, то из сервиса address-book будут запрошены отписки пользователя. Если в ответе будет указано, что email отписан от рассылок данной компании, то сообщение по адресу отправляться не будет. При этом в Kafka будет записано событие Rejected(9) с описанием rejected_unsubscribed.
Sender string Данные отправителя
Subject string Тема письма
Body object Тело письма
AttachmentsIds
(optional)
array[integer] Массив файлов, прикрепленных к письму

Внимание

Чтобы заполнить параметр AttachmentsIds, сначала для каждого прикрепляемого к письму файла надо вызвать POST /files/files, получить fileId и указать его в AttachmentsIds.

Recipients

Параметр Тип данных Описание и Допустимые значения
MergeFields
(optional)
string Пользовательские макросы в виде "ключ":"значение"
Например:
ExtraData
(optional)
string Любая дополнительная информация в виде "ключ":"значение"
Address string Адрес получателя
Name
(optional)
string Имя получателя

Sender

Параметр Тип данных Описание и Допустимые значения
Address string Адрес отправителя
Name
(optional)
string Имя отправителя

Body

Должен быть обязательно заполнен один из параметр: или Html или PlainText.

Параметр Тип данных Описание и Допустимые значения
Html
(optional)
string Тело письма в виде html
PlainText
(optional)
string Тело письма «как есть», все теги отображаются как обычный текст

Внимание

Тело сообщения кроме пользовательских макросов, задаваемых в Recipients.MergeFields, может содержать еще 2 макроса: [Unsubscribe] и [WebVersion].
Макрос отписки [Unsubscribe] нужно обязательно указать в Body, иначе сообщение не будет отослано.

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

curl -X POST \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: application/json' \
 -d '
{
  "Recipients": [
    {
      "MergeFields": {"Name":"Иван"},
      "Address": "ivan@ivanmail.ru",
    }
  ],
  "СheckUnsubscription": true,
  "Sender": {
    "Address": "info@test.com",
    "Name": "TestShop"
  },
  "Subject": "Тестовое сообщение",
  "Body": {
    "Html": "<p>[Name], Добро пожаловать!</p>[Unsubscribe]"
  },
  "AttachmentsIds": [
    "312e628f-65dc-4d1d-a12e-64d86b6c06ca"
  ]
}' https://api.devino.online/email/messages

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

{
  "Result": [
    {
      "Index": "52342355",
      "Address": "info@test.com",
      "MessageId": "43432",
      "Code": "ok"
    }
  ],
  "Code": "ok"
}

Параметры ответа

Параметр Тип данных Описание и допустимые значения
Result string Массив с ответами по каждому из посланных сообщений
Code string Указывает на результат обработки сообщения:
ok - успешно обработано
validation_error - ошибка валидации
internal_error - внутренняя ошибка
Description
(optional)
string Описание ошибки.
Указывается если code не ok
Reasons
(optional)
Array[String, String] Массив ошибок, произошедших во время обработки сообщения.
Указывается если code не ok
reasons.key string Код ошибки
reasons.ref
(optional)
string Ссылка на параметр, в котором произошла ошибка

Result

Параметр Тип данных Описание и допустимые значения
Index integer Позиция получателя из массива переданных Recipient'ов
Address string Адрес получателя
MessageId string Идентификатор сообщения
Code string Код ответа для конкретного сообщения:
ok - успешно обработано
validation_error - ошибка валидации
internal_error - внутренняя ошибка
Description string Описание ошибки.
Указывается если code не ok
Reasons
(optional)
Array[String, String] Массив ошибок, произошедших во время обработки сообщения.
Указывается если code не ok
reasons.key string Код ошибки
reasons.ref
(optional)
string Ссылка на параметр, в котором произошла ошибка

Webhook

При формировании статуса сообщения будет отправлен POST-запрос на URL, указанный при отправке сообщения в параметре Recipients.ExtraData в callbackUrl. В ответ на запрос ожидается 200 Ok.

В случае, если на запрос вернётся 500 Internal Error, то будут предприниматься попытки доставки статуса 5 раз с интервалом в минуту.

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

[
  {
    "channel": "EMAIL",
    "messageId": "dRJ7nkr99WF",
    "ts": 1636976602504,
    "status": "SENT",
    "taskId": 0,
    "triggerId": 0,
    "email": "example@devinotele.com"
  }
]

Параметры запроса

Параметр Тип данных Описание и Допустимые значения
channel string Канал отправки (будет указан "EMAIL")
messageId string Уникальный идентификатор сообщения на платформе
ts long Указывает на время создания объекта status
status string Статус (см. Возможные статусы)
taskId long Уникальный идентификатор рассылки
triggerId long Уникальный идентификатор триггера рассылки
email string Email адрес

Возможные статусы

Параметр Описание
ACCEPTED Сообщение было принято
SENT Было отправлено
DELIVERED Сообщение доставлено полуателю
OPENED Сообщение было прочитано
CLICKED Получатель перешел по ссылке в сообщении
BOUNCED Не удалось доставить сообщение
REJECTED Сообщение было отклонено оператором или Devino
SUBSCRIBED Получатель подписался на рассыку
UNSUBSCRIBED Получатель отписался от рассылки
COMPLAINED Получатель пожаловался на рассылку

Положить файл в хранилище

Для того чтобы положить файл в хранилище (для дальнйшего прикрепления его к email'у) необходимо вызвать POST /files/files, передавая в теле параметры сообщения с указанием данных авторизации в заголовке.

Параметры запроса

Параметр Тип данных Описание и Допустимые значения
category string Зарезервированное значение EMAIL_ATTACHMENT
file file Файл

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

curl -X POST https://api.devino.online/files/files?category=EMAIL_ATTACHMENT \
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
 -H 'Content-Type: multipart/form-data' \
 -F 'file=@letter.png;type=image/png' \

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

{
  "result": {
    "fileId": "efc1c054-9d65-4c21-b01f-cb0986c2dccb",
    "publicUrl": "http://files.local/emailAttachments/efc1c054-9d65-4c21-b01f-cb0986c2dccb"
  }
}

Параметры ответа

Параметр Тип данных Описание и допустимые значения
fileId string Идентификатор файла
publicUrl string URL файла для скачивания