EMAIL HTTP API¶

Описание¶

API предоставляет удобный интерфейс для автоматизации процесса отправки email-рассылок через платформу Devino Telecom. С помощью API можно:

отправлять массовые и транзакционные email-рассылки
управлять рассылками
получать статистику по рассылкам

Для использования API необходима авторизация по логину паролю от личного кабинета Devino Telecom.

Внимание

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

Авторизация¶

API поддерживает базовую авторизацию через заголовок Authorization. В заголовке запроса необходимо передать логин и пароль из личного кабинета в формате 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

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

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

https://integrationapi.net/addressbook/v2/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 обязательный	integer	ID рассылки (предаётся в url)

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

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

ContactDto¶

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

ContactGroupDto¶

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

EmailAddress¶

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

TaskType¶

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

SmsResendTaskDto¶

Параметр	Тип данных	Описание
ContactGroupId обязательный	integer	Группа контактов для переотправки
Text обязательный	string	Текст SMS
SenderAddress обязательный	string	Адрес отправителя
StartDelay обязательный	TimeSpan	Задержка после отправки email-рассылки

EmailTaskCounters¶

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

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

{
    "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 возвращается ID рассылки и набор счётчиков. При их расчёте учитываются только уникальные группы и контакты (из нескольких групп с одинаковыми идентификаторами учитывается только одна).

Максимальное количество получателей в одной рассылке - 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	Пользовательский ID рассылки
Contacts	ContactDto[]	Список контактов
ContactGroups	ContactGroupDto[]	Список групп контактов
TemplateId	string	ID шаблона
SmsResendTask	SmsResendTaskDto	Данные для переотправки смс в случае непрочтения письма
SendDuplicates	bool	Отправлять дубликаты или нет (по умолчанию - нет)

ContactDto¶

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

ContactGroupDto¶

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

SmsResendTaskDto¶

Параметр	Тип данных	Описание
Text обязательный	string	Текст SMS
SenderAddress обязательный	string	Адрес отправителя
StartDelay обязательный	TimeSpan	Задержка после отправки email-рассылки

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

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

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

{
    "Name":"test",
    "Sender":{
        "Address":"xxx@gmail.com",
        "Name":"yyy"
    },
    "Subject":"test subj",
    "Body": {
        "Html": "test [Unsubscribe][WebVersion]",
        "PlainText": "test"
    },
    "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 обязательный	integer	ID рассылки (предаётся в 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	integer	ID рассылки (предаётся в URL)

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

Параметр	Тип данных	Описание
TemplateId	integer	ID шаблона
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Body	Body	Объект, который содержит HTML и PlainText письма
UserTemplateId	string	Внешний ID
MergeFields	array[str]	Доступные ключи для персонализации

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

{
    "Result":{
        "MergeFields":[],
        "Name": "test",
        "Sender":{},
        "Body": {
            "Html": "test [Unsubscribe] [WebVersion]",
            "PlainText": "test message"
        },
        "TemplateId": 1
    },
    "Code": "ok",
    "Description": "ok"
}

Получение списка шаблонов¶

GET Templates/

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

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

Параметр	Тип данных	Описание
TemplateId	integer	ID шаблона
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Body	Body	Объект, который содержит HTML и PlainText письма
UserTemplateId	string	Внешний ID

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

{
    "Result":[
        {
            "Name": "test",
            "Sender":{},
            "Body": {
                "Html": "test [Unsubscribe] [WebVersion]",
                "PlainText": "test message"
            },
            "TemplateId": 1
        },
        {
            "Name": "test",
            "Sender":{},
            "Body": {
                "Html": "test [Unsubscribe] [WebVersion]",
                "PlainText": "test message"
            },
            "TemplateId": 2
        }
    ],
    "Code": "ok",
    "Description": "ok"
}

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

POST /Templates

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

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

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

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

Параметр	Тип данных	Описание
Name обязательный	string	Название шаблона
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Body обязательный	Body	Объект, содержащий HTML и PlainText шаблона
UserTemplateId	string	Внешний ID

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

{
    "Name":"test",
    "Sender":{
        "Name":"good sender"
    },
    "Body": {
        "Html": "test [Unsubscribe] [WebVersion]",
        "PlainText": "test message"
    }
}

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

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

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

PUT Templates/{TemplateId}

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

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

Параметр	Тип данных	Описание
TemplateId обязательный	integer	ID шаблона, полученный из метода Templates POST
Name обязательный	string	Название шаблона
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Body обязательный	Body	Объект, содержащий HTML и PlainText шаблона
UserTemplateId	string	Внешний ID

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

Параметр	Тип данных	Описание
TemplateId	integer	ID шаблона
Name	string	Название
Sender	EmailAddress	Отправитель - адрес и имя
Subject	string	Тема
Body	Body	Объект, содержащий HTML и PlainText шаблона
UserTemplateId	string	Внешний ID

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

{
    "Name":"test",
    "Sender":{
        "Name":"good sender"
    },
    "Body": {
        "Html": "test [Unsubscribe] [WebVersion]",
        "PlainText": "test message"
    }
}

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

{
    "Result":{
        "Name":"test",
        "Sender":{"Name":"good sender"},
        "Body": {
            "Html": "test [Unsubscribe] [WebVersion]",
            "PlainText": "test message"
        },
        "TemplateId": 1
    },
    "Code": "ok",
    "Description": "ok"
}

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

DELETE Templates/{TemplateId}

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

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

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

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

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

Статистика¶

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

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

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

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

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

Сервис рассчитан на получение в параметрах либо TaskId, - тогда возвращается статистика по сообщениям, отправленным в рамках рассылки с указанным IDом 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 обязательный	integer	ID рассылки, в рамках которой были созданы сообщения, для которых необходимо вернуть статистику.
StartDateTime обязательный	DateTime	Дата в формате UTC, задающая начало временного диапазона, которому должны принадлежать сообщения, для которых необходимо вернуть статистику.
EndDateTime обязательный	DateTime	Дата в формате UTC, задающая конец временного диапазона, которому должны принадлежать сообщения, для которых необходимо вернуть статистику.
State	string	Выполняет роль фильтра, требует вернуть статистику по тем сообщениям, что находятся в указанном состоянии.
Range обязательный	ItemsRange	Диапазон

Сервис рассчитан на получение параметров либо TaskId - тогда возвращается статистика по сообщениям, отправленным в рамках рассылки с указанным IDом 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 возвращается ID сообщения (string).

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

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

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

Параметр	Тип данных	Описание
Sender обязательный	array[string]	Отправитель - адрес и имя
Recipients обязательный	array[object]	Список получателей
Subject обязательный	array[string]	Тема письма
Body обязательный	array[string]	Тело сообщения HTML и PlainText
TemplateId	string	ID шаблона
UserCampaignId	string	ID рассылки в системе пользователя
#### Recipient

Параметр	Тип данных	Описание
MergeFields	Массив string	Пользовательские макросы вида ключ – значение. В названии макроса запрещены специальные символы
RecipientId	string	Пользовательский ID получателя, не более 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 возвращается ID сообщения (string).

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

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

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

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

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

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

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

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

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

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

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

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 на своем внутреннем ресурсе. Форматы коллбэков: json или XML.

Внимание

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

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

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

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

Параметр	Тип данных	Описание	Доступен в событиях
messageId	string	ID сообщения	Во всех
taskId	integer	ID рассылки	Во всех
userMessageId	string	Клиентский ID сообщения	Во всех, кроме `delivered`, `bounced`, `complained`
userCampaignId	string	Клиентский ID кампании	Во всех, кроме `delivered`, `bounced`, `complained`
email	string	Email получателя	Во всех
event	Event	Событие	Во всех
url	string	URL, по которому перешел получатель	`clicked`
dateTime	string	Дата и время события	Во всех
clientInfo	ClientInfo	Информация о получателе	`opened`, `clicked`, `unsubscribed`
isHardbounce	bool	Указывает на то, является ли передаваемый статус hard bounce	По умолчанию `NULL`. Заполняется только в случае если поле event равен `Bounced`
reason	string	Содержит причину, по которой сообщение не было принято почтовым сервером.	По умолчанию `NULL`. Заполняется только в случае если поле event равен `Bounced`

Информация

В случае, если параметр недоступен в событии, то значение параметра будет 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 будут пустыми.

Reason¶

Значение	Описание
already_unsubscribed	Получатель отписан от рассылок
bad-configuration	Некорректная конфигурация
bad-connection	Ошибка в соединении
bad-domain	Домен не принимает почту или не существует
bad-mailbox	Адрес не существует, доставка не удалась
content-related	Заблокировано из-за содержания
inactive-mailbox	Адрес когда-то существовал, но сейчас отключен
invalid-sender	Неправильный адрес отправителя
message-expired	Истек срок давности доставки
no-answer-from-host	Сервер получателя не отвечает
other	Неизвестная ошибка
overpackage-related	Превышение пакета
policy-related	Не соответствует настройкам правил сервера получателя
protocol-errors	Отклонено из-за ошибок SMTP
quota-issues	Адрес существует, но почта не принимается, т.к. исчерпана дисковая квота
relaying-issues	Ошибка ретрансляции
routing-errors	Ошибка маршрутизации
spam-related	Сообщение отвергнуто сервером получателя как спам
virus-related	Отклонено как инфицированное

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

Sent

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "SENT",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "clientInfo": 
            {
                "platform": null,
                "operatingSystem": null,
                "browser": null,
                "userAgent": null,
                "ipAddress": null,
                "geolocation": 
                {
                    "country": null,
                    "region": null,
                    "city": null
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Delivered

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "DELIVERED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "clientInfo": 
            {
                "platform": null,
                "operatingSystem": null,
                "browser": null,
                "userAgent": null,
                "ipAddress": null,
                "geolocation": 
                {
                    "country": null,
                    "region": null,
                    "city": null
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Opened

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "OPENED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "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
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Clicked

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "CLICKED",
            "url": "http://example.com",
            "dateTime": "2020-01-14T08:27:57.7377849",
            "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
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Unsubscribed

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "UNSUBSCRIBED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "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
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Subscribed

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "SUBSCRIBED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "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
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

Bounced

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "BOUNCED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "clientInfo": 
            {
                "platform": null,
                "operatingSystem": null,
                "browser": null,
                "userAgent": null,
                "ipAddress": null,
                "geolocation": 
                {
                    "country": null,
                    "region": null,
                    "city": null
                }
            },
            "isHardbounce": true,
            "reason": "bad-mailbox"
        }
    ]
}

Complained

{
    "messageEventDtos": 
    [
        {
            "messageId": "MsA29aT4zJe",
            "taskId": 0,
            "userMessageId": "userMessageId-1234",
            "userCampaignId": "UserCampaignId-1234",
            "email": "address@example.com",
            "event": "COMPLAINED",
            "url": null,
            "dateTime": "2020-01-14T08:27:57.7377849",
            "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
                }
            },
            "isHardbounce": null,
            "reason": null
        }
    ]
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<messageEventDtos>
    <messageEventDto>
        <messageId>MsAqJyjEjwP</messageId>
        <taskId>0</taskId>
        <userMessageId>UserMessageId-1234</userMessageId>
        <userCampaignId>UserCampaignId-1234</userCampaignId>
        <email>address@example.com</email>
        <event>SENT</event>
        <dateTime>2020-01-14T08:34:02.9306227</dateTime>
        <clientInfo>
            <geolocation/>
        </clientInfo>
    </messageEventDto>
</messageEventDtos>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<messageEventDtos>
    <messageEventDto>
        <messageId>MsA247Nalun</messageId>
        <taskId>0</taskId>
        <userMessageId>userMessageId-1234</userMessageId>
        <userCampaignId>UserCampaignId-1234</userCampaignId>
        <email>address@example.com</email>
        <event>BOUNCED</event>
        <dateTime>2020-01-14T08:26:27.0083642</dateTime>
        <clientInfo>
            <geolocation/>
        </clientInfo>
        <isHardbounce>true</isHardbounce>
        <reason>bad-mailbox</reason>
    </messageEventDto>
</messageEventDtos>

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<messageEventDtos>
    <messageEventDto>
        <messageId>MsAqREbsSUB</messageId>
        <taskId>0</taskId>
        <userMessageId>UserMessageId-1234</userMessageId>
        <userCampaignId>UserCampaignId-1234</userCampaignId>
        <email>address@example.com</email>
        <event>BOUNCED</event>
        <dateTime>2020-01-14T08:33:12.1570284</dateTime>
        <clientInfo>
            <geolocation/>
        </clientInfo>
        <isHardbounce>false</isHardbounce>
        <reason>already_unsubscribed</reason>
    </messageEventDto>
</messageEventDtos>