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 | Идентификатор сообщения |
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 |
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
}
}
}