EMAIL HTTP API

Обзор

API предоставляет удобный интерфейс для автоматизации процесса отправки email-рассылок через платформу Devino Telecom. С помощью API можно отправлять массовые и транзакционные email-рассылки, управлять рассылками, получать полноценную статистику. Работа с API осуществляется в соответствии с принципами REST, посредством HTTP-запросов с использованием методов GET, POST, PUT, PATCH и DELETE. Для использования API необходима авторизация. Авторизация происходит по логину паролю от Личного Кабинета платформы Devino Telecom.

Предупреждение

Внимание! С 1 апреля стала доступна вторая версия Email API. С этого момента первая версия API не поддерживается.

Предупреждение

Внимание! В тексте обязательно должны присутствовать ссылка на отписку и ссылка на веб-версию.

Авторизация

API поддерживает базовую авторизацию через заголовок Authorization (https://en.wikipedia.org/wiki/Basic_access_authentication). В заголовке запроса необходимо передать логин и пароль из Личного Кабинета в формате login:password в base64 кодировке.

*Authorization: Basic dGVzdGVyOjExMTExMQ==*

Формат запроса

Запрос к API задается в следующем формате:

{тип_метода} https://integrationapi.net/email/v{версия}/{ресурс}?{параметры}

где:

{тип_метода} - HTTP метод GET, POST, PUT, PATCH и DELETE.
{версия} - Версия API. Текущая версия - 2.
{ресурс} - URL ресурса, над которым выполняется действие. Список всех ресурсов смотрите в соответствующем разделе.
{параметры} - обязательные и необязательные параметры запроса, которые не входят в состав URL ресурса.
Обязательный пункт: Accept */*

Сервис позволяет передавать параметры и получать ответы в следующих форматах: JSON и XML.

Формат ответа

Ответ API состоит из двух частей:

• Код с описанием - эта часть присутствует во всех ответах.
• Результат - специфичный для каждого запроса. Может отсутствовать.

{
  "Result": {},
  "Code": "not_found",
  "Description": "user not found"
}

Код можно использовать для проверки статуса запроса, а описание предназначено для диагностики возможных проблем. Описание может быть изменено в новой версии API без предупреждения о нарушении обратной совместимости. Набор кодов также может быть расширен.

Список кодов ответов:

Код	HTTP status	Расшифровка
ok	200, 201	Запрос выполнен успешно
validation_error	400 - 404	Ресурс не изменён
internal_error	500	Внутренняя ошибка сервиса, можно повторить запрос позже

Запрос диапазонов

Некоторые запросы предполагают возвращение только части данных. Для таких запросов необходимо передавать специальный заголовок:

Range: items=1-100

Оба предела диапазона включаются. При отсутствии заголовка такие запросы возвращают ошибку validation_error с http кодом 416 RequestedRangeNotSatisfiable.

Локализация

В поле Description может возвращаться локализованная строка с текстом ошибки. Для этого необходимо передать заголовок Accept-Language с нужным языком. В текущей версии поддерживаются русский и английский языки. По умолчанию, если заголовок не передан или язык не найден среди доступных возвращаются ответы на английском.

Accept-Language: ru-RU

Управление адресами отправителя

Получение адресов отправителя

GET /UserSettings/SourceAddresses

Метод возвращает адреса отправителя авторизованного пользователя - подтверждённые и запрошенные.

Возвращаемый результат - список записей.

Параметр	Тип данных	Описание
SourceAddress	string	Адрес отправителя
State	SourceAddressState	Статус адреса отправителя 0 - Запрошен (Request) 1 - Подтверждён (Approve) 2 - Отклонён (Reject) 3 - Удалён (Deleted)
IsDefault	bool	Флаг, указывающий является ли адрес адресом по умолчанию

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

{
    "Result":[
        {
            "SourceAddress": "blabla@gmail.com",
            "State": 1,
            "IsDefault": true
        },
        {
            "SourceAddress": "eeee@mailforspam.com",
            "State": 1,
            "IsDefault": false
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

Добавление адреса отправителя

POST /UserSettings/SourceAddresses

Метод отправляет запрос на подтверждение нового адреса отправителя. Адрес должен быть валидным email адресом. На этот адрес отправляется письмо, чтобы пользователь подтвердил, что адрес принадлежит именно ему. Если запрос был успешно отправлен, возвращается код «ok» и http код 201. Метод возвращает только стандартный ответ, без поля Result.

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

Параметр	Тип данных	Описание
SenderAddress	string	Адрес отправителя

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

{
    "SourceAddress":"test@gmail.com"
}

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

{
    "Code": "ok",
    "Description": "ok"
}

Удаление адреса отправителя

DELETE UserSettings/SourceAddresses/{SourceAddress}

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

Параметр	Тип данных	Описание
SourceAddress	string	Адрес отправителя

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

{
    "Code": "ok",
    "Description": "ok"
}

Управление рассылками

Получение списка рассылок

GET /Tasks

Возвращает список рассылок.

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

Параметр	Тип данных	Описание
CreatorLogin	string	Логин создателя рассылки, задаёт фильтр (будут возвращены только те рассылки, что были созданы от имени указанного логина создателя рассылки).
Range	ItemsRange	Диапозон

Метод требует аутентификации с помощью BasicAuthentication Header. Список рассылок возвращается именно для того, кто авторизовался через BasicAuthentication, если только авторизованный не обладает правами админа и параметром Login не задан другой логин. В случае, если задан CreatorLogin, в ответ попадут только те рассылки, что были созданы сублогином, заданным в CreatorLogin.

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

{
    "Result": [
        {
            "SourceName": "test",
            "Price": 0.23,
            "SendDuplicates": false,
            "Cancellable": true,
            "Deletable": false,
            "NextStartDateTime": "/Date(1473417269843-0000)/",
            "State": "Waiting",
            "TotalContacts": 10000,
            "CompletedContacts": 10000,
            "ErrorCount": 0,
            "IsExecuting": false,
            "ServiceType": "Email",
            "IsSmooth": false,
            "IsPersonalized": false,
            "ID": 130872,
            "Name": "test",
            "OwnerLogin": "test",
            "Type": "Distribution",
            "Groups": [],
            "IncludedContacts": [],
            "ExcludedContacts": [],
            "ManualContacts": [],
            "StopList": [],
            "Text": "<p>test</p>",
            "Subject": "test",
            "MessageValidity": 0,
            "MessageType": "Email",
            "TaskMessageType": "11",
            "DoTransliterate": false,
            "SourceAddress": "pavel.voropaev@seedway.ru",
            "StartDateTime": "/Date(1395809939517-0000)/",
            "Period": "None",
            "GlobalState": "Paused",
            "GlobalStateInfo":{
                "State": "Paused"
            },
            "PercentageCompleted": 100,
            "MessageValidityAsTimeSpan": "1.00:00:00"
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

Получение рассылки

GET /Tasks/{TaskId}

Метод возвращает данные о рассылке.

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

Параметр	Тип данных	Обязательность	Описание
TaskId	int	Да	Идентификатор рассылки (предаётся в url)

Возвращаемый результат:

Параметр	Тип данных	Описание
TaskId	int	Идентификатор рассылки
Login	string	Логин пользователя
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Text	string	Текст
StartDateTime	DateTime	Начало отправки в UTC формате
EndDateTime	DateTime	Окончание отправки в UTC формате (для плавных рассылок)
Type	TaskType	Тип рассылки
UserCampaignId	string	Пользовательский идентификатор рассылки
Contacts	ContactDto[]	Список контактов
ContactGroups	ContactGroupDto[]	Список групп контактов
State	TaskState	Статус рассылки
Price	decimal	Цена за сообщение
CreatorLogin	string	Логин создателя рассылки (сублогин из ролевой модели)
SendDuplicates	bool	Отправлять дубликаты или нет (по умолчанию - нет)
Counters	EmailTaskCounters	Количество контактов (общее, дубликаты, отписавшиеся, исключённые)

ContactDto

Параметр	Тип данных	Описание
Id	long	Идентификатор контакта
Included	bool	Включать или исключать контакт из рассылки (true или false)

ContactGroupDto

Параметр	Тип данных	Описание
Id	long	Идентификатор группы контакта
Included	bool	Включать или исключать группу из рассылки (true или false)

EmailAddress

Параметр	Тип данных	Описание
Name	string	Имя
Address	string	Адрес

TaskType

Текст	Число	Описание
Distribution	1	Одноразовая рассылка
Birthday	2	Рассылка по дням рождения

EmailTaskCounters

Параметр	Тип данных	Описание
TaskId	int	Идентификатор рассылки
TotalContacts	int	Количество получателей
Dublicates	int	Количество отфильтрованных дубликатов
Unsubscribed	int	Количество отфильтрованных отписавшихся
Excluded	int	Количество отфильтрованных исключённых контактов
OverPackage	int	Контакты сверх пакета (на них отправки не будет)
SpamScore	int	Оценка спамности письма

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

{
    "Result":{
        "Login": "TEST",
        "Name": "q",
        "Sender":{
            "Address": "xxx@gmail.com",
            "Name": "yyy"
        },
        "Subject": "%Имя%",
        "Text": "blablabla",
        "StartDateTime": "/Date(1440501564737-0000)/",
        "UserCampaignId": "",
        "State": "Finished",
        "Price": 10,
        "Counters":{
            "TotalContacts": 2,
            "Duplicates": 0,
            "Unsubscribed": 0,
            "Excluded": 0,
            "OverPackage": 0,
            "SpamScore": 2.2,
            "TaskId": 10500700
        },
        "Type": "Distribution",
        "Contacts":[
            {
                "Id": 7907323000,
                "Included": true
            },
            {
                "Id": 8603950002,
                "Included": true
            }
        ],
        "ContactGroups":[],
        "CreatorLogin": "TEST",
        "SendDuplicates": false,
        "TaskId": 10592701
    },
    "Code": "ok",
    "Description": "ok"
}

Создание рассылки

POST /Tasks

Метод создаёт рассылку. Если рассылка была успешно создана, возвращается код «ok» и http код 201. В качестве Result возвращается идентификатор рассылки и набор счётчиков. При их расчёте учитываются только уникальные группы и контакты (из нескольких групп с одинаковыми идентификаторами учитывается только одна). Максимальный размер рассылки - 2 млн контактов.

Порядок вычисления счётчиков:

• дубли
• исключённые группы и контакты
• отписавшиеся

Валидируются: * текст - на отсутствие стоп-слов и на наличие макросов [Unsubscribe] и [WebVersion] * тема - на отсутствие стоп-слов * размер текста и темы (не более 10 МБ) * отправитель - имя на отсутствие стоп-слов и подтверждён ли адрес * группы контактов - на существование * тип рассылки - допустимы только 1 (Distribution) и 2 (Birthday). * логин - на существование (не актуально для внешнего API) * шаблон - на существование

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

Параметр	Тип данных	Описание	Обязательный
Name	string	Название	Да
Sender	EmailAddress	Отправитель - адрес и имя	Да
Subject	string	Тема	Да
Text	string	Текст	Да
StartDateTime	DateTime	Начало отправки в UTC формате	Нет
EndDateTime	DateTime	Окончание отправки в UTC формате (для плавных рассылок)	Нет
Type	TaskType	Тип рассылки	Да
UserCampaignId	string	Пользовательский идентификатор рассылки	Нет
ContactGroups	ContactGroupDto[]	Список групп контактов	Нет
TemplateId	string	Идентификатор шаблона	Нет
SendDuplicates	bool	Отправлять дубликаты или нет (по умолчанию - нет)	Нет

ContactGroupDto:

Параметр	Тип данных	Описание	Обязательный
Id	long	Идентификатор контакта	Да
included	bool	Включать или исключать группу из рассылки (true или false)	Да

Возвращаемый результат:

Параметр	Тип данных	Описание
TaskId	int	Идентификатор рассылки
TotalContacts	int	Количество получателей
Dublicates	int	Количество отфильтрованных дубликатов
Unsubscribed	int	Количество отфильтрованных отписавшихся
Excluded	int	Количество отфильтрованных исключённых контактов
OverPackage	int	Контакты сверх пакета (на них отправки не будет)
SpamScore	int	Оценка спамности письма

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

{
    "Name":"test",
    "Sender":{
        "Address":"xxx@gmail.com",
        "Name":"yyy"
    },
    "Subject":"test subj",
    "Text":"test [Unsubscribe][WebVersion]",
    "StartDateTime":"08/31/2015 13:30:38",
    "UserCampaignId":"",
    "ContactGroups":[
        {
            "Id":252,
            "Included":true
        },
        {
            "Id":234,
            "Included":true
        }
    ]
}

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

{
    "Result":{
        "TaskId": 133875,
        "TotalContacts": 1,
        "Dublicates": 0,
        "Unsubscribed": 0,
        "Excluded": 0
    },
    "Code": "ok",
    "Description": "new task added"
}

Редактирование рассылки

PUT /Tasks/{TaskId}

Метод редактирования рассылки. Если рассылка была успешно отредактирована, возвращается код «ok» и http код 200. Параметры запроса и ответ идентичны Tasks POST. Редактировать можно только рассылки в статусе «New». При этом все поля являются обязательными и заменяются.

Изменение статуса рассылки

PUT /Tasks/{TaskId}/State

Обновление статуса рассылки для остановки, возобновления, отмены, удаления. Возвращается только стандартный ответ.

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

Параметр	Тип данных	Описание	Обязательный
TaskId	int	Идентификатор рассылки (предаётся в url)	Да
State	TaskState	Текстовый или числовой статус рассылки	Да

TaskState:

Текст	Число	Описание	Можно ли использовать этот статус для PUT
New	0	Статус только что добавленной рассылки	Да
Created	1	Создание рассылки завершено, рассылка готова к выполнению	Да
Started	2	Рассылка отправляется (также используется для возобновления после остановки)	Да
Stopped	3	Рассылка остановлена (с возможностью возобновления)	Да
Canceled	4	Рассылка отменена (без возможности возобновления)	Да
Finished	5	Оправка рассылки завершена успешно	Да
Deleted	6	Рассылка удалена	Да
Failed	7	При отправке рассылки произошла ошибка	Да

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

{
    "State":1
}

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

{
    "Code": "ok",
    "Description": "ok"
}

Шаблоны

Получение шаблона

GET Templates/{TemplateId}

Метод получения шаблона. В качестве результата возвращается шаблон.

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

Параметр	Тип данных	Описание
TemplateId	int	Идентификатор рассылки (предаётся в url)

Возвращаемый результат

Параметр	Тип данных	Описание
TemplateId	int	Идентификатор шаблона
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Text	string	Текст
UserTemplateId	string	Внешний идентификатор

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

{
    "Result":{
        "Login": "tester",
        "Name": "test",
        "Sender":{},
        "Text": "test [Unsubscribe] [WebVersion]",
        "TemplateId": 1
    },
    "Code": "ok",
    "Description": "ok"
}

Создание шаблона

POST /Templates

Метод добавляет шаблон. Если шаблон успешно добавлен, возвращается код «ok» и http код 201. В качестве Result возвращается идентификатор шаблона (int).

Валидируются: * наличие непустого названия * текст - на отсутствие стоп-слов и на наличие макросов [Unsubscribe] и [WebVersion] * тема - на отсутствие стоп-слов * размер текста и темы (не более 10 МБ) * отправитель - имя на отсутствие стоп-слов и подтверждён ли адрес

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

Параметр	Тип данных	Описание	Обязательный
Name	string	Название шаблона	Да
Sender	EmailAddress	Отправитель - адрес и имя	Нет
Subject	string	Тема	Нет
Text	string	Текст	Да
UserTemplateId	string	Внешний идентификатор	Нет

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

{
    "Name":"test",
    "Sender":{
        "Name":"good sender"
    },
    "Text":"good text [Unsubscribe] [WebVersion]"
}

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

{
    "Result": 123,
    "Code": "ok",
    "Description": "ok"
}

Обновление шаблона

PUT Templates/{TemplateId}

Метод обновления шаблона. Если шаблон был успешно обновлён, возвращается код «ok» и http код 200 и обновлённый шаблон.

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

Параметр	Тип данных	Описание	Обязательный
TemplateId	int	Идентификатор шаблона, полученный из метода Templates POST	Да
Name	string	Название шаблона	Да
Sender	EmailAddress	Отправитель - адрес и имя	Нет
Subject	string	Тема	Нет
Text	string	Текст	Да
UserTemplateId	string	Внешний идентификатор	Нет

Возвращаемый результат

Параметр	Тип данных	Описание
TemplateId	int	Идентификатор шаблона
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Text	string	Текст
UserTemplateId	string	Внешний идентификатор

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

{
    "Name":"test",
    "Sender":{
        "Name":"good sender"
    },
    "Text":"good text [Unsubscribe] [WebVersion]"
}

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

{
    "Result":{
        "Login":"tester",
        "Name":"test",
        "Sender":{"Name":"good sender"},
        "Text":"good text [Unsubscribe] [WebVersion]",
        "TemplateId": 1
    },
    "Code": "ok",
    "Description": "ok"
}

Удаление шаблонов

DELETE Templates/{TemplateId}

Удаление шаблона. Возвращается только стандартный ответ.

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

Параметр	Тип данных	Описание	Обязательный
TemplateId	int	Идентификатор шаблона, полученный из метода Templates POST	Да

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

{
    "Code": "ok",
    "Description": "ok"
}

Статистика

Получение статистики

GET /Statistics?Login={Login}&TaskId={TaskId}&StartDateTime={StartDateTime}&EndDateTime={EndDateTime}

Получение статистики по сообщениям в виде набора счётчиков (сколько было отправлено, сколько было доставлено, сколько не было отправлено и т.д.).

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

Параметр	Тип данных	Описание	Обязательный
TaskId	int	Идентификатор рассылки, в рамках которой были созданы сообщения, для которых необходимо вернуть статистику.	Да
StartDateTime	DateTime	Дата в формате UTC, задающая начало временного диапазона, которому должны принадлежть сообщения, для которых необходимо вернуть статистику.	Да
EndDateTime	DateTime	Дата в формате UTC, задающая конец временного диапазона, которому должны принадлежть сообщения, для которых необходимо вернуть статистику.	Да

Сервис расчитан на получение в параметрах либо TaskId, - тогда возвращается статистика по сообщениям, отправленным в рамках рассылки с указанным идентификатором TaskId, - либо StartDateTime и EndDateTime, - тогда возвращается статистика по сообщениям, отправленным за временной диапазон, заданный с помощью StartDateTime и EndDateTime (даты должны быть приведены к UTC зоне).

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

{
    "Result": {
        "NotSent": 30,
        "Sent": 0,
        "Delivered": 0,
        "Read": 0,
        "Clicked": 0,
        "Bounced": 0,
        "Rejected": 0,
        "Total": 30
    },
    "Code": "ok",
    "Description": "ok"
}

Получение детализации

GET /Statistics/Messages?Login={Login}&TaskId={TaskId}&StartDateTime={StartDateTime}&EndDateTime={EndDateTime}&State={State}

Получение детализации по сообщениям.

Параметр	Тип данных	Описание	Обязательный
TaskId	int	Идентификатор рассылки, в рамках которой были созданы сообщения, для которых необходимо вернуть статистику.	Да
StartDateTime	DateTime	Дата в формате UTC, задающая начало временного диапазона, которому должны принадлежть сообщения, для которых необходимо вернуть статистику.	Да
EndDateTime	DateTime	Дата в формате UTC, задающая конец временного диапазона, которому должны принадлежть сообщения, для которых необходимо вернуть статистику.	Да
State	string	Выполняет роль фильтра, требует вернуть статистику по тем сообщениям, что находятся в указанном состоянии.	Нет
Range	ItemsRange	Диапозон	Да

Сервис расчитан на получение параметров либо TaskId, - тогда возвращается статистика по сообщениям, отправленным в рамках рассылки с указанным идентификатором TaskId, - либо StartDateTime и EndDateTime, - тогда возвращается статистика по сообщениям, отправленным за временной диапазон, заданный с помощью StartDateTime и EndDateTime (даты должны быть приведены к UTC зоне), так же в заголовках необходимо передавать диапазон в формате Range: items=1-100.

Параметр State является опциональным и может применяться в обоих из ранее описанных сценариев, - тогда возвращается ранее описанная статистика по сообщениями, находящимя в указанном состоянии.

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

{
    "Result": [
        {
            "State": "NotSent",
            "Price": 0,
            "Id": 141471292110003601,
            "DestinationEmail": "user@devinotele.com",
            "LastUpdateUtc": "/Date(1485937304700-0000)/",
            "CreatedDateUtc": "/Date(1485937304000-0000)/"
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

Отправка транзакционного сообщения

POST v2/messages

Метод отправляет транзакционное сообщение нескольким получателям с возможностью использования макросов. Если сообщение успешно добавлено в очередь, возвращается код «ok» и http код 201. В качестве Result возвращается идентификатор сообщения (string).

Валидируются:

• текст - на отсутствие стоп-слов (нецензурная лексика)
• тема - на отсутствие стоп-слов
• размер текста и темы (не более 10 МБ)
• отправитель - имя на отсутствие стоп-слов и подтверждён ли адрес
• получатель - имя на отсутствие стоп-слов и валидность e-mail адреса, также проверяется по списку отписавшихся
• шаблон - на существование

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

Параметр	Тип данных	Описание	Обязательный
Sender	Массив String	Отправитель - адрес и имя	Да
Recipients	Список	Список получателей (см. табл. 2)	Да
Subject	String	Тема письма	Да
Body	Массив String	Тело сообщения HTML и PlainText	Да
TemplateId	String	Идентификатор шаблона	Нет
UserCampaignId	String	Идентификатор рассылки в системе пользователя	Нет

Recipient:

Параметр	Тип данных	Описание	Обязательный
MergeFields	Массив String	Пользовательские макросы вида ключ – значение. В названии макроса запрещены спец. символы	Нет
RecipientId	String	Пользовательский идентификатор получателя, не более 32 символов	Нет
Address	String	Адрес получателя	Да
Name	String	Имя получателя	Нет

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

{
    "Sender":{
        "Address": "sourceaddress@example.com",
        "Name": "Test"
    },
    "Recipients": [
        {
            "MergeFields": {
            "ExtField":"5 дней",
            "Name": "Иван"
        },
            "RecipientId": "",
            "Address": "ivan@example.com",
            "Name": "Ivan"
        }
    ],
    "Subject": "Ув. [Name]!",
    "Body": {
        "Html": "Ув. [Name]! Осталось [ExtField]<br><a href=\"[Unsubscribe]\">Отписаться</a>",
        "PlainText": "Ув. {ExtField}! Ждем вас завтра! [Unsubscribe]"
    },
    "UserCampaignId": "1234"
}

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

{
    "Result": [
        {
            "Index":0,
            "Address":"ivan@example.com",
            "MessageId":"Mdz0i7z1Dyp",
            "Code":"ok"
        }
    ],
    "Code":"ok",
    "Description":"ok"
}

Сценарии:

• Перед началом отправки необходимо подтвердить адрес отправителя
• В текст письма может быть включен макрос [Unsubscribe] - на его место будет подставлена ссылка на страницу отписки.

Отправка транзакционного сообщения (old)

POST /Messages

Предупреждение

С выходом Email API v2 данный метод не поддерживается

Метод отправляет транзакционное сообщение. Если сообщение успешно добавлено в очередь, возвращается код «ok» и http код 201. В качестве Result возвращается идентификатор сообщения (string).

Валидируются:

• текст - на отсутствие стоп-слов (нецензурная лексика)
• тема - на отсутствие стоп-слов
• размер текста и темы (не более 10 МБ)
• отправитель - имя на отсутствие стоп-слов и подтверждён ли адрес
• получатель - имя на отсутствие стоп-слов и валидность e-mail адреса, также проверяется по списку отписавшихся
• шаблон - на существование

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

Параметр	Тип данных	Описание	Обязательный
Sender	EmailAddress	Отправитель - адрес и имя	Да
Recipient	EmailAddress	Получатель - адрес и имя	Да
Subject	string	Тема	Да
Text	string	Текст	Да
UserMessageId	string	Идентификатор сообщения в системе пользователя	Нет
UserCampaignId	string	Идентификатор рассылки в системе пользователя	Нет
TemplateId	string	Идентификатор шаблона (внешний или внутренний)	Нет

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

{
    "Sender":{
        "Address":"test@test.com",
        "Name":"name"
    },
    "Recipient":{
        "Address":"test@supertest.com",
        "Name":"name"
    },
    "Subject":"test subj",
    "Text":"test"
}

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

{
    "Result": "kaAtrHbZ72",
    "Code": "ok",
    "Description": "message queued to send"
}

Сценарии:

• Перед началом отправки необходимо подтвердить адрес отправителя(«Sender»: {«Address»})
• В текст письма может быть включен макрос [Unsubscribe] - на его место будет подставлена ссылка на страницу отписки.

Получение статусов транзакционных сообщений

GET /Messages/{MessageId},{MessageId}

Метод используется для получения статусов транзакционных сообщений. Допускается передача сразу нескольких идентификаторов сообщений через запятую. Можно передавать не более 300 идентификаторов. При этом возвращаются статусы только уникальных сообщений и только сообщений доступных пользователю.

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

Параметр	Тип данных	Описание	Обязательный
MessageId	string	Идентификатор сообщения (предаётся в url, можно указать несколько через запятую)	Да

Возвращаемый результат (массив для нескольких сообщений)

Параметр	Тип данных	Описание
MessageId	string	Идентификатор сообщения
Email	string	Email получателя
State	string	Статус сообщения
RecipientId	string	Пользовательский идентификатор получателя

State

Значение	Описание
NotSent	Отправляется
Sent	Отправлено
Delivered	Доставлено
Read	Прочитано
Clicked	Переход по ссылке
Bounced	Не удалось доставить
Rejected	Отклонено (сообщение не было отправлено)

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

{
    "Result":[
        {
            "MessageId": "y49EiXaPY1",
            "Email": "ftw@gmail.com",
            "State": "Sent"
        },
        {
            "MessageId": "y49cjxHxxI",
            "Email": "blabla@gmail.com",
            "State": "NotSent"
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

Получение callback

Данный метод позволяет не обращаться к API Devino каждый раз, когда требуется получить статус доставки сообщения, а обрабатывать входящие события от платформы Devino на своем внутреннем ресурсе.

Предупреждение

Внимание! Для подключения URL для приема статусов Email-сообщений обратитесь к вашему менеджеру или напишите письмо в техническую поддержку support@devinotele.com

Запросы производятся по следующим событиям:

• Отправлено (Sent)
• Доставлено (Delivered)
• Прочитано (Opened)
• Переход по ссылке (Clicked)
• Не удалось доставить (Bounced)
• Отписался от рассылки (Unsubscribed)
• Подписался на рассылки (Subscribed)
• Жалоба (Complained)

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

Параметр	Тип данных	Описание	Доступен в событиях
messageId	string	Идентификатор сообщения	Во всех
taskId	int	Идентификатор рассылки	Во всех
userMessageId	string	Клиентский идентификатор сообщения	Во всех, кроме delivered bounced, complained
userCampaignId	string	Клиентский идентификатор кампании	Во всех, кроме delivered bounced, complained
email	string	Email получателя	Во всех
event	Event	Событие	Во всех
url	string	Url, по которому перешел получатель	clicked
dateTime	string	Дата и время события	Во всех
clientInfo	ClientInfo	Информация о получателе	opened, clicked, unsubscribed

В случае, если параметр недоступен в событии, то значение параметра будет null

Event

Значение	Описание
SENT	Отправлено
DELIVERED	Доставлено
OPENED	Прочитано
CLICKED	Переход по ссылке
BOUNCED	Не удалось доставить
UNSUBSCRIBED	Получатель отписался
SUBSCRIBED	Получатель подписался
COMPLAINED	Получатель пожаловался

ClientInfo

Значение	Описание
platform	Тип платформы. Например, DESKTOP
operatingSystem	Операционная система
browser	Браузер
userAgent	userAgent
ipAddress	IP адрес
geolocation	Геолокация

Geolocation

Значение	Описание
country	Страна
region	Регион
city	Город

В данный момент геолокация не определяется, поэтому в ближайшее время параметры country, region и city будут пустыми.

Пример запроса Sent:

{
    "messageId":"MdbsucAq4Ro",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"SENT",
    "url":null,
    "dateTime":"2018-03-29T16:41:57.7943021",
    "clientInfo":{
        "platform":null,
        "operatingSystem":null,
        "browser":null,
        "userAgent":null,
        "ipAddress":null,
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Delivered:

{
    "messageId":"MdzY0T1MFtT",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"DELIVERED",
    "url":null,
    "dateTime":"2018-04-02T17:16:56",
    "clientInfo":{
        "platform":null,
        "operatingSystem":null,
        "browser":null,
        "userAgent":null,
        "ipAddress":null,
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Opened:

{
    "messageId":"MdbsucAq4Ro",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"OPENED",
    "url":null,
    "dateTime":"2018-03-29T16:43:07.8801537",
    "clientInfo":{
        "platform":"DESKTOP",
        "operatingSystem":"Windows",
        "browser":"Outlook",
        "userAgent":"Mozilla/4.0(compatible;MSIE7.0;WindowsNT10.0;Win64;x64;Trident/7.0;.NET4.0C;.NET4.0E;.NETCLR2.0.50727;.NETCLR3.0.30729;.NETCLR3.5.30729;ASU2JS;MicrosoftOutlook16.0.9029;ms-office;MSOffice16)",
        "ipAddress":"192.168.0.1",
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Clicked:

{
    "messageId":"MdbsucAq4Ro",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"CLICKED",
    "url":"http://example.com",
    "dateTime":"2018-03-29T16:44:31.536724",
    "clientInfo":{
        "platform":"DESKTOP",
        "operatingSystem":"Windows",
        "browser":"Chrome",
        "userAgent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
        "ipAddress":"192.168.0.1",
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Unsubscribed:

{
    "messageId":"MdbsucAq4Ro",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"UNSUBSCRIBED",
    "url":null,
    "dateTime":"2018-03-29T16:46:53.412013",
    "clientInfo":{
        "platform":"DESKTOP",
        "operatingSystem":"Windows",
        "browser":"Chrome",
        "userAgent":"Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/65.0.3325.181Safari/537.36",
        "ipAddress":"192.168.0.1",
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Subscribed:

{
    "messageId":"MdbsucAq4Ro",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"SUBSCRIBED",
    "url":null,
    "dateTime":"2018-03-29T16:47:13.5839294",
    "clientInfo":{
        "platform":"DESKTOP",
        "operatingSystem":"Windows",
        "browser":"Chrome",
        "userAgent":"Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/65.0.3325.181Safari/537.36",
        "ipAddress":"192.168.0.1",
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Bounced:

{
    "messageId":"MdzY0T1MFtT",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"BOUNCED",
    "url":null,
    "dateTime":"2018-04-02T17:16:56",
    "clientInfo":{
        "platform":null,
        "operatingSystem":null,
        "browser":null,
        "userAgent":null,
        "ipAddress":null,
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}

Пример запроса Complained:

{
    "messageId":"MdzY0T1MFtT",
    "taskId":0,
    "userMessageId":null,
    "userCampaignId":null,
    "email":"address@example.com",
    "event":"COMPLAINED",
    "url":null,
    "dateTime":"2018-04-02T17:16:56",
    "clientInfo":{
        "platform":null,
        "operatingSystem":null,
        "browser":null,
        "userAgent":null,
        "ipAddress":null,
        "geolocation":{
            "country":null,
            "region":null,
            "city":null
        }
    }
}