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

EMAIL

Отправка

Для отправки Email-сообщения необходимо:

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

Параметр Тип данных Описание
Recipients array[Recipients] Массив данных получателей.
Sender Sender Данные отправителя.
Subject string Тема письма.
Body Body Текст письма.
AttachmentsIds
(optional)
array[string] Массив файлов, прикрепленных к письму.
CheckUnsubscription
(optional)
boolean

Проверка на наличие отписок у получателей письма.

Если true, то из базы контактов будут запрошены отписки получателя. По умолчанию false.

Если в ответе будет указано, что email отписан от рассылок данной компании, то письмо по адресу отправляться не будет.

Внимание

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

Recipients

Параметр Тип данных Описание
Address string Email-адрес получателя.
Name
(optional)
string Имя получателя.
MergeFields
(optional)
string

Пользовательские макросы в виде JSON-объекта для подстановки в текст письма (объект Body).

Например:
{ "Birthday": "12.03.1999", "Name": "Maria" }

ExtraData
(optional)
string

Данные, которые будут указаны в коллбэке со статусом сообщения.

Любой массив вида "key":
{ "key1": "value1", "key2": "value2" }

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. ok - успешно обработано.
2. Validation failed - ошибка валидации.

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