EMAIL¶

Отправка¶

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

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

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

Параметр	Тип данных	Описание
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	Ссылка на параметр, в котором произошла ошибка.

Примеры ответов¶

OK

{
  "result": [
    {
      "index":0,
      "address":"recipient.1@email.com",
      "messageId":"dwY4BSnjQ2X"
    },
    {
      "index":1,
      "address":"recipient.2@email.com",
      "messageId":"dwY4BSnjQ2i"
    }
  ],
  "description":"ok"
}

VALIDATION FAILED

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