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 | Уникальный идентификатор триггера рассылки |
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 файла для скачивания |