EMAIL¶
Отправка¶
Для отправки Email-сообщения необходимо:
- Создать домен отправителя рассылки. Это можно сделать в личном кабинете или через техническую поддержку.
- Вызвать POST /email/messages, передавая параметры сообщения в теле запроса и данные авторизации в заголовке.
Параметры запроса¶
Параметр | Тип данных | Описание |
---|---|---|
Recipients | array[Recipients] | Массив данных получателей. |
Sender | Sender | Данные отправителя. |
Subject | string | Тема письма. |
Body | Body | Текст письма. |
AttachmentsIds (optional) |
array[string] | Массив файлов, прикрепленных к письму. |
CheckUnsubscription (optional) |
boolean | Проверка на наличие отписок у получателей письма. Если Если в ответе будет указано, что email отписан от рассылок данной компании, то письмо по адресу отправляться не будет. |
Внимание
Чтобы прикрепить файлы к письму, нужно предварительно вызвать POST /files/files для каждого файла в отдельности. В ответе на запрос будет параметр fileId
. Все полученные fileId
указываются в массиве AttachmentsIds
.
Recipients¶
Параметр | Тип данных | Описание |
---|---|---|
Address | string | Email-адрес получателя. |
Name (optional) |
string | Имя получателя. |
MergeFields (optional) |
string | Пользовательские макросы в виде JSON-объекта для подстановки в текст письма (объект Например: |
ExtraData (optional) |
string | Данные, которые будут указаны в коллбэке со статусом сообщения. Любой массив вида |
Sender¶
Параметр | Тип данных | Описание |
---|---|---|
Address | string | Email-адрес отправителя. Предварительно должен быть создан и согласован домен. |
Name (optional) |
string | Имя отправителя. Максимальная длина - 150 символов. |
Body¶
Обязательно должен быть заполнен один из параметров: или Html
, или PlainText
.
Параметр | Тип данных | Описание |
---|---|---|
Html (optional) |
string | Тело письма в формате HTML. |
PlainText (optional) |
string | Тело письма в формате Plaintext, все теги отображаются как обычный текст. |
Внимание
Кроме пользовательских макросов в параметре MergeFields
(объект Recipients), тело сообщения также может содержать макросы:
[Unsubscribe]
[WebVersion]
Макрос отписки [Unsubscribe]
нужно обязательно указать в Body
, иначе сообщение не будет отправлено.
Пример запроса¶
{
"Recipients": [
{
"MergeFields": { "Name": "Иван" },
"Address": "ivan@ivanmail.ru",
}
],
"CheckUnsubscription": true,
"Sender": {
"Address": "info@test.com",
"Name": "TestShop"
},
"Subject": "Тестовое сообщение",
"Body": {
"Html": "<p>[Name], Добро пожаловать!</p>[Unsubscribe]"
},
"AttachmentsIds": [
"312e628f-65dc-4d1d-a12e-64d86b6c06ca.png"
]
}
Параметры ответа¶
Параметр | Тип данных | Описание |
---|---|---|
result | array[object] | Массив с данными по отправленным сообщений. Указывается только при "code": "ok" . |
result.index | integer | Порядковый номер получателя из массива переданных получателей (объект Recipients). |
result.address | string | Email-адрес получателя. |
result.messageId | string | ID сообщения. |
Description | string | Указывает на результат обработки сообщения: 1. |
Reasons |
array | Массив ошибок, произошедших во время обработки сообщения. Указывается только при "Description": "Validation failed" . |
Reasons.Key | string | Код ошибки. |
Reasons.Reference | string | Ссылка на параметр, в котором произошла ошибка. |
Примеры ответов¶
{
"result": [
{
"index":0,
"address":"recipient.1@email.com",
"messageId":"dwY4BSnjQ2X"
},
{
"index":1,
"address":"recipient.2@email.com",
"messageId":"dwY4BSnjQ2i"
}
],
"description":"ok"
}
{
"Description":"Validation failed",
"Reasons": [
{
"Key":"validation.recipients.must.be.greater.then.0",
"Reference":"recipients"
}
]
}
Коллбэки¶
Как подключить
Для настройки коллбэков со статусами сообщений необходимо обратиться к менеджеру компании или в техническую поддержку.
Возможные статусы¶
Код | Описание |
---|---|
ACCEPTED | Сообщение было принято. |
SENT | Сообщение было отправлено в сеть оператора. |
DELIVERED | Сообщение доставлено получателю. |
EXPIRED | Истек срок жизни сообщения. |
OPENED | Сообщение было прочитано. |
CLICKED | Получатель перешел по ссылке в сообщении. |
BOUNCED | Не удалось доставить сообщение. |
REJECTED | Сообщение было отклонено оператором или Devino.Online. |
SUBSCRIBED | Получатель подписался на рассылку. |
UNSUBSCRIBED | Получатель отписался от рассылки. |
COMPLAINED | Получатель пожаловался на рассылку. |
Пример коллбэка¶
[
{
"messageId": "dRJ7nkr99WF",
"ts": 1636976602504,
"status": "SENT",
"email": "example@devinotele.com"
}
]
Положить файл в хранилище¶
Чтобы прикрепить файл к email-сообщению, необходимо заранее положить нужный файл в хранилище. Для этого необходимо вызвать POST /files/files, передавая параметры файла в заголовке с указанием данных авторизации.
Параметры запроса¶
Параметр | Тип данных | Описание |
---|---|---|
category | string | Зарезервированное значение EMAIL_ATTACHMENT . |
file | string | Ссылка на файл. Можно загружать файлы в форматах: .xls, .xlsx, .doc, .docx, .pdf, .jpg, .jpeg, .png, .img, .bmp, .rar, .txt |
Пример запроса¶
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' \
Параметры ответа¶
Параметр | Тип данных | Описание |
---|---|---|
fileId | string | ID файла. Его нужно указать в запросе отправки email-сообщения. |
publicUrl | string | URL файла для скачивания. |
Пример ответа¶
{
"result": {
"fileId": "efc1c054-9d65-4c21-b01f-cb0986c2dccb.png",
"publicUrl": "http://files.local/emailAttachments/efc1c054-9d65-4c21-b01f-cb0986c2dccb.png"
}
}