EMAIL HTTP API

Обзор

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

Работа с API осуществляется в соответствии с принципами REST, посредством HTTP-запросов с использованием методов GET, POST, PUT, PATCH и DELETE.

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

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

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

Авторизация

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 Отправлять дубликаты или нет (по умолчанию - нет)
SmsResendTask SmsResendTaskDto Данные для переотправки через смс
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 Рассылка по дням рождения

SmsResendTaskDto

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

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

ContactDto

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

ContactGroupDto:

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

SmsResendTaskDto

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

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

Параметр Тип данных Описание
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",
    "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 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 Тема
Body Body Объект, который содержит HTML и PlainText письма
UserTemplateId string Внешний идентификатор
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 int Идентификатор шаблона
Name string Название
Sender EmailAddress Отправитель - адрес и имя
Subject string Тема
Body Body Объект, который содержит HTML и PlainText письма
UserTemplateId string Внешний идентификатор

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

{
    "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 возвращается идентификатор шаблона (int).

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

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

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

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

{
    "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 int Идентификатор шаблона, полученный из метода Templates POST Да
Name string Название шаблона Да
Sender EmailAddress Отправитель - адрес и имя Нет
Subject string Тема Нет
Body Body Объект, cодержащий HTML и PlainText шаблона Да
UserTemplateId string Внешний идентификатор Нет

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

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

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

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

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

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

Параметр Тип данных Описание Обязательный
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 на своем внутреннем ресурсе. Формат Callback: json или XML.

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

Внимание! Для подключения 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
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>