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 файла для скачивания