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	Не удалось доставить сообщение (hard bounce email-адрес).
REJECTED	Сообщение было отклонено оператором или Devino.Online.
SUBSCRIBED	Получатель подписался на рассылку.
UNSUBSCRIBED	Получатель отписался от рассылки.
COMPLAINED	Получатель пожаловался на рассылку.

Пример коллбэка¶

[
  {
    "dateTime": "2023-04-04T05:56:56.313Z",
    "userData": null,
    "contactId": null,
    "messageId": "dRJ7nkr99WF",
    "taskId": 0,
    "event": "ACCEPTED",
    "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"
  }
}

Детализация¶

Для получения детальных сведений об отправленных сообщениях необходимо вызвать GET /email-statistics/statistics/detail, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
limit	integer	Количество сообщений в результатах поиска.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
taskId (optional)	integer	ID рассылки, по которой нужно получить детализацию. Можно узнать при создании сценария рассылки. Используется в обязательной комбинации параметров.
triggerId (optional)	integer	ID триггера рассылки. Можно узнать при получении сценария рассылки. Используется в обязательной комбинации параметров.
dateTimeFrom (optional)	datetime	Дата начала поиска сообщений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo (optional)	datetime	Дата окончания поиска сообщений. Используется в обязательной комбинации параметров. Формат `YYYY-MM-DD+hh:mm:ss`.
messageIds (optional)	array[integer]	ID сообщений, по которым нужно получить детализацию. Используется в обязательной комбинации параметров.
order (optional)	string	В каком порядке выводить результаты запроса. Возможные значения: ○ `ASC` - в возрастающем порядке. ○ `DESC` - в убывающем порядке.
orderBy (optional)	string	Поле, по которому будут отсортированы результаты запроса.
recipient (optional)	string	Email-адрес получателя.
sourceAddress (optional)	string	Email-адрес отправителя.
status (optional)	string	Статус сообщений в результатах поиска. Возможные значения: ○ `DELIVERED` - сообщение доставлено получателю. ○ `IN_PROGRESS` - сообщение находится в процессе отправки. ○ `READ` - сообщение было прочитано получателем. ○ `REDIRECT` - получатель перешел по ссылке в сообщении. ○ `UNDELIVERED` - сообщение не доставлено. ○ `SUBSCRIBED` - получатель подписался на рассылку. ○ `UNSUBSCRIBED` - получатель отписался от рассылки.
timeOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).
userId (optional)	integer	ID пользователя, проводившего рассылку.

Комбинации параметров¶

Для корректной работы метода в запросе необходимо использовать одну из этих комбинаций параметров в соответствии со списком:

ID рассылки: taskId
ID рассылки и триггера: taskId, triggerId
Даты начала и окончания поиска сообщений: dateTimeFrom, dateTimeTo
ID рассылки, триггера; даты начала и окончания поиска сообщений: taskId, triggerId, dateTimeFrom, dateTimeTo
ID сообщений: messageIds

Поля для параметра `orderBy`¶

Используются в параметрах orderBy для сортировки результатов поиска.

Название поля	Описание
COMPANY_ID	ID компании.
COMPANY_NAME	Название компании.
EVENT_DATE_TIME	Дата и время последнего обновления статуса сообщения.
MESSAGE_ID	ID сообщения.
PRICE	Стоимость сообщения.
RECIPIENT	Email-адрес получателя.
SENT_DATE_TIME	Дата и время отправки сообщения.
SOURCE_ADDRESS	Email-адрес отправителя.
SOURCE_NAME	Имя отправителя.
STATUS	Статус сообщения.
SUBJECT	Тема письма.
TASK_ID	ID рассылки.
TASK_NAME	Название рассылки.
TASK_TYPE	Тип рассылки.
TRIGGER_CONTACT_GROUP	Название списка контактов, по которому проходила рассылка. В ответе на запрос будет обозначен как параметр `list`.
TRIGGER_SEGMENT	Название сегмента списка контактов, по которому проходила рассылка. В ответе на запрос будет обозначен как параметр `segment`.
IS_CONTACT_GROUP_DELETED	Удален ли список контактов, контакту которого было отправлено сообщение. В ответе на запрос будет обозначен как параметр `isListDeleted`.
IS_TRIGGER_SEGMENT_DELETED	Удален ли сегмент списка контактов, контакту которого было отправлено сообщение. В ответе на запрос будет обозначен как параметр `isSegmentDeleted`.
TRIGGER_ID	ID триггера рассылки.
USER_ID	ID пользователя, отправившего сообщения.
USER_LOGIN	Логин пользователя, отправившего сообщения.

Примеры запросов¶

С датами

curl -X GET https://api.devino.online/email-statistics/statistics/detail?dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-02-24+00:00:00&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

С ID рассылки и триггера

curl -X GET https://api.devino.online/email-statistics/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

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

Параметр	Тип данных	Описание
data	array[object]	Массив объектов с детальной информацией по каждому сообщению. Параметры определяются полями, которые были заданы в изначальном запросе.
size	integer	Количество элементов на странице и сообщений в результатах поиска. Задается параметром `limit`.
offset	integer	Смещение результатов поиска. То есть, к примеру, если в параметре будет указано число `5`, полученный массив сообщений будет отображаться, начиная с 5 позиции.
number	integer	Номер полученной страницы. Определяется параметром `offset`. ○ Если значение параметра `offset` будет `0` при любом значении параметра `limit`, то номер полученной страницы будет `1`. ○ Если `offset` будет больше `0`, но меньше, чем значение параметра `limit`, номер страницы будет `2`. Например, при `"offset": 5` и `"limit": 10`, значение параметра `number` будет `2`. ○ Если `offset` будет больше чем `limit`, то номер страницы будет определяться целочисленным делением `offset` на `limit` плюс 1 (`offset` / `limit` + 1). Например, при `"offset": 1000` и `"limit": 50`, значение параметра `number` будет `21` (`1000` / `50` + 1 = `21`).
pageExists	boolean	Существует ли отображаемая страница.
total	integer	Общее количество сообщений, по которым можно получить детализацию.
pages	integer	Общее количество страниц, по которым можно получить детализацию. Определяется целочисленным делением параметра `total` на `limit` (`total` / `limit`).
more	boolean	Индикатор: существуют ли страницы после текущей, указанной в параметре `number`.

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

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "recipient": "recipient@example.com",
        "sourceAddress": "sender@example.com",
        "sourceName": "sendersName",
        "sentDateTime": "2022-12-14 05:55:32",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "subject": "Special event",
        "companyId": 234,
        "companyName": "Company",
        "userId": 88,
        "userLogin": "79991112233",
        "taskId": 6666666,
        "triggerId": "22569",
        "price": "1.0000",
        "isListDeleted": false
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Статистика сообщений¶

Для загрузки общей статистики по статусам сообщений необходимо вызвать GET /omni-statistics-exporter/export/statistics/sliced-by-event-time, передавая параметры фильтров и данные авторизации в заголовке.

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

Параметр	Тип данных	Описание
groupBy	string	Группировка результатов: ○ `NONE` - без группировки ○ `YEAR` - по годам ○ `MONTH` - по месяцам ○ `WEEK` - по неделям ○ `DAY` - по дням ○ `HOUR` - по часам
dateTimeFrom	datetime	Дата начала периода сбора статистики. Формат `YYYY-MM-DD+hh:mm:ss`.
dateTimeTo	datetime	Дата окончания периода сбора статистики. Формат `YYYY-MM-DD+hh:mm:ss`.
charset (optional)	string	Кодировка полученных данных. Доступны значения `CP1251` и `UTF8`.
taskId (optional)	integer	ID рассылки, по которой нужно получить статистику.
triggerId (optional)	integer	ID триггера рассылки, по которому нужно получить статистику.
userId (optional)	integer	ID пользователя, совершавшего рассылки.
zoneOffset (optional)	integer	Часовой пояс получателя. Формат - смещение в минутах, например, `180` для Москвы (GMT+3).

Пример запроса¶

curl -X GET https://api.devino.online/email-stat/statistics/sliced-by-event-time?dateTimeFrom=2023-02-12+00:00:00&dateTimeTo=2023-04-12+00:00:00&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

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

Данные ответа форматированы в формате таблицы с параметрами:

Информация

Последняя строка таблицы - статистика за весь указанный период.

Параметр	Описание
Send date	Дата сбора статистики в зависимости от значения параметра `groupBy`.
Sent	Количество принятых к отправке сообщений.
Delivered	Количество доставленных сообщений.
Delivery rate	Процент доставленных сообщений от общего числа.
Bounced	Количество недоставленных сообщений (hard bounce email-адреса).
Bounce rate	Процент недоставленных сообщений (hard bounce email-адреса).
Opened	Количество прочитанных получателем сообщений.
Open rate	Процент прочитанных получателем сообщений.
Clicked	Количество сообщений, где получатель перешел по ссылке.
Click to Open Rate	Процент сообщений, где получатель перешел по ссылке, от количества прочитанных сообщений. Например, если сообщение открыли 100 раз и из них по ссылке перешли 20 раз, то значение параметра будет `20`.
Unsubscribed	Количество сообщений, где получатель отписался от рассылки.
Unsubscribe Rate	Процент сообщений, где получатель отписался от рассылки.
Complained	Количество сообщений, которые получатель пометил как спам.
Spam rate	Процент сообщений, которые получатель пометил как спам.

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

Send date;Sent;Delivered;Delivery rate;Bounced;Bounce rate;Opened;Open rate;Clicked;Click to Open Rate;Unsubscribed;Unsubscribe Rate;Complained;Spam rate;
01.04.2022;0;0;0%;0;0%;0;0%;0;0%;0;0%;0;0%
01.05.2022;2;2;100%;0;0%;0;0%;0;0%;0;0%;0;0%
01.06.2022;914;904;98.91%;0;0%;0;0%;0;0%;0;0%;0;0%
01.07.2022;18;3;16.67%;0;0%;0;0%;0;0%;1;33.33%;0;0%
01.08.2022;0;0;0%;0;0%;0;0%;0;0%;0;0%;0;0%
01.09.2022;32;18;56.25%;0;0%;0;0%;1;0%;1;5.56%;0;0%
01.10.2022;4108031;4108041;100%;3;0%;6;0%;6;100%;0;0%;0;0%
01.11.2022;980578;980574;100%;0;0%;0;0%;0;0%;0;0%;0;0%
01.12.2022;5;4;80%;1;20%;0;0%;0;0%;0;0%;0;0%
01.02.2023;51;51;100%;0;0%;0;0%;0;0%;0;0%;0;0%
12.04.2022 - 12.04.2023;5089631;5089597;100%;4;0%;6;0%;7;116.67%;2;0%;0;0%

EMAIL¶

Отправка¶

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

Recipients¶

Sender¶

Body¶

Пример запроса¶

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

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

Коллбэки¶

Возможные статусы¶

Пример коллбэка¶

Положить файл в хранилище¶

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

Пример запроса¶

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

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

Детализация¶

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

Комбинации параметров¶

Поля для параметра orderBy¶

Примеры запросов¶

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

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

Статистика сообщений¶

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

Пример запроса¶

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

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

Поля для параметра `orderBy`¶