EMAIL HTTP API

Обзор

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

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

Внимание! Для использования данного вида интеграции необходимо обратиться к своему менеджеру, либо в техническую поддержку support@devinotele.com для настройки доступа.

Авторизация

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. Текущая версия - 1.
{ресурс} - URL ресурса, над которым выполняется действие. Список всех ресурсов смотрите в соответствующем разделе.
{параметры} - обязательные и необязательные параметры запроса, которые не входят в состав URL ресурса.
Обязательный пункт: Accept */*

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

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

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

  • Код с описанием - эта часть присутствует во всех ответах.
  • Результат - специфичный для каждого запроса. Может отсутствовать.
{
  "Result":
    {
        ...
    },
    "Code": "not_found",
    "Description": "user not found"
}

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

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

Код HTTP status Расшифровка
ok 200, 201 Запрос выполнен успешно
not_changed 200 Ресурс не изменён
invalid_email 400 Передан невалидный email адрес
not_found 404 Ресурс не найден
empty_value 400 Не передан один из обязательный параметров
invalid_value 400 Передано невалидное значение параметра
missing_macros 400 Не найден один из обязательных макросов в тексте рассылки
size_exceeded 400 Превышен допустимый размер данных
internal_error 500 Внутренняя ошибка сервиса
not_available 400 Действие не доступно
invalid_permission 403 Не достаточно разрешений для вызова метода
access_denied 403 Нет доступа к запрошенному ресурсу
authorization_failed 401 Ошибка авторизации

Ресурсы

Список всех ресурсов, которые предоставляет API:

Ресурс Метод Описание
/Tasks/{TaskId}/State PUT Изменение статуса рассылки
/Tasks/{TaskId}/Attachments GET Получение аттачей рассылки
/Tasks/{TaskId}/Attachments POST Добавление аттача в рассылку
/Tasks/{TaskId}/Attachments DELETE Удаление аттачей из рассылки
/Tasks/{TaskId} GET Получение рассылки
/Tasks/{TaskId} PATCH Редактирование рассылки
/Tasks POST Создание рассылки
/Messages POST Отправка транзакционного сообщения

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

ET /Tasks/{TaskId}

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

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

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

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

Параметр Тип данных Описание
TaskId int Идентификатор рассылки
Login string Логин пользователя
Name string Название
Sender EmailAddress Отправитель - адрес и имя
Subject string Тема
Text string Текст
StartDateTime DateTime Начало отправки в UTC формате
Type TaskType Тип рассылки
UserCampaignId string Пользовательский идентификатор рассылки
State TaskState Статус рассылки
Price decimal Цена за сообщение
ContactsCount int Количество контактов

EmailAddress

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

TaskType

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

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

{
    "Result":
    {
        "Login": "login",
        "Name": "name",
        "Sender":
        {
            "Address": "xxx@gmail.com",
            "Name": "sendername"
        },
        "Subject": "subject",
        "Text": "text",
        "StartDateTime": "/Date(1440501564737-0000)/",
        "UserCampaignId": "",
        "State": "Started",
        "Price": 100000,
        "ContactsCount": 9997,
        "TaskId": 123456,
        "Type": 1
    },
    "Code": "ok",
    "Description": "found it!"
}

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

POST EmailApi/Tasks

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

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

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

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

Параметр Тип данных Описание Обязательный
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"
}

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

PATCH /EmailApi/Tasks/{TaskId}

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

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

PUT /EmailApi/Tasks/{TaskId}/State

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

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

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

TaskState:

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

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

{"State":1}

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

{
    "Code": "ok",
    "Description": "task state updated to Created"
}

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

POST /EmailApi/Messages

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

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

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

Аттачи валидируются на:

  • наличие имени файла и данных
  • расширение файла, исполняемые файлы не допускаются
  • размер (не более 3 МБ каждый)

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

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

AttachmentDto:

Параметр Тип данных Описание Обязательный
ContentId string ContentId в теле письма для встроенных аттачей Нет
FileName string Имя файла Да
Data string Данные аттача в base64 кодировке Да

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

{
   "Sender": {"Address":"test@test.com","Name":"name"},
   "Recipient": {"Address":"test@supertest.com", "Name":"name" },
   "Subject":"test subj",
   "Attachments":[{"ContentID": "Picture.jpg","FileName":"Picture.jpg","Data":"/9j/4AAQSkZJ"}],
   "Text":"test"
}

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

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

Сценарии:

  • Перед началом отправки необходимо подтвердить адрес отправителя(“Sender”: {“Address”})
  • В текст письма может быть включен макрос [Unsubscribe] - на его место будет подставлена ссылка на страницу отписки.
  • Для отправки письма с встроенным аттачем, в параметре Attachments необходимо указать ContentId и вставить его в текст рассылки следующим образом: <img src=’cid:<ContentId>’/> , иначе аттач придет как обычное вложение.

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

GET EmailApi/Messages/{MessageId},{MessageId}

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

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

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

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

Параметр Тип данных Описание
MessageId string Идентификатор сообщения
Email string Email получателя
State 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"
}