API

Введение

Проект предоставляет RESTful API для управления подписчиками, создания шаблонов и выполнения рассылок. Все ответы API имеют Content-Type: application/json и содержат валидный JSON (за исключением ответов c кодом 204). Все запросы к API также должны иметь Content-Type: application/json.

Авторизация

Авторизация производится при помощи ключа доступа, который клиент указывает в HTTP-заголовке X-Auth-Token. Ключ предоставляет доступ к ресурсам одного проекта.

Ресурсы

Проект

Информация о проекте содержит следующие поля:

  • name: имя проекта Mailtank
  • from_email: e-mail адрес, с которого отправляются письма проекта
GET /project

Возвращает иформацию о текущем проекте

GET /project HTTP/1.1
HTTP/1.0 200 OK

{
    "name": "project name",
    "from_email": "no-reply@project.domain"
}

Подписчики

Информация о подписчике содержит следующие поля:

  • does_email_exist (read-only): имеет истинное значение, если Mailtank не получал уведомлений от внешных систем о том, что данный e-mail не существует;
  • email: уникальный в рамках проекта e-mail;
  • id: уникальный в рамках проекта идентификатор подписчика;
  • properties: словарь свойств подписчика, которые доступны в шаблоне рассылки;
  • tags: список тегов подписчика;
  • url (read-only): resource URI.
GET /subscribers/?page=(int: page)

Возвращает постраничный список подписчиков проекта.

Query Parameters:
 
  • page (int) – (опционально) номер запрашиваемой страницы
GET /subscribers/ HTTP/1.1
HTTP/1.0 200 OK

{
    "objects": [
        {
            "does_email_exist": true,
            "email": "james@doe.com",
            "id": "1",
            "properties": {
                "age": 21,
                "first_name": "James",
                "last_name": "Doe"
            },
            "tags": [
                "test-tag"
            ],
            "url": "/subscribers/1"
        },
        {
            "does_email_exist": true,
            "email": "john@doe.com",
            "id": "192f56eb9b",
            "properties": {},
            "tags": [],
            "url": "/subscribers/192f56eb9b"
        }
    ],
    "total": 2,
    "page": 1,
    "pages_total": 1
}
POST /subscribers/

Создаёт нового подписчика.

Json Parameters:
 
  • email (string) – e-mail подписчика. Должен быть уникальным в рамках проекта.
  • id (string) – (опционально) идентификатор подписчика. Должен быть уникальным в рамках проекта. Будет сгенерирован системой автоматически, если не указан в запросе.
  • properties (dict) – (опционально) словарь свойств подписчика, ключи которого являются строками, а значения – строками или числами
  • tags (list) – (опционально) список тегов подписчика

Для создания подписчика достаточно указать e-mail:

POST /subscribers/ HTTP/1.1

{
    "email": "john@doe.com"
}
HTTP/1.0 201 CREATED

{
    "does_email_exist": true,
    "email": "john@doe.com",
    "id": "192f56eb9b",
    "properties": {},
    "tags": [],
    "url": "/subscribers/192f56eb9b"
}

Нельзя создать второго подписчика с одним и тем же адресом:

POST /subscribers/ HTTP/1.1

{
    "email": "john@doe.com"
}
HTTP/1.0 400 BAD REQUEST

{
    "email": ["Entry with such value already exists."]
}

При создании подписчика можно указать идентификатор, теги и свойства:

POST /subscribers/ HTTP/1.1

{
    "email": "james@doe.com",
    "id": "1",
    "properties": {
        "age": 21,
        "first_name": "James",
        "last_name": "Doe"
    },
    "tags": [
        "test-tag"
    ]
}
HTTP/1.0 201 CREATED

{
    "does_email_exist": true,
    "email": "james@doe.com",
    "id": "1",
    "properties": {
        "age": 21,
        "first_name": "James",
        "last_name": "Doe"
    },
    "tags": [
        "test-tag"
    ],
    "url": "/subscribers/1"
}
PUT /subscribers/(str: id)

Обновляет данные подписчика.

Json Parameters:
 
  • email (string) – (опционально) e-mail подписчика
  • properties (dict) – (опционально) словарь свойств подписчика
  • tags (list) – (опционально) список тегов подписчика
PUT /subscribers/1 HTTP/1.1

{
    "properties": {
        "age": 25,
        "first_name": "James",
        "last_name": "Doe",
        "sex": "M"
    },
    "tags": [
        "male",
        "yet-another-test-tag"
    ]
}
HTTP/1.0 200 OK

{
    "does_email_exist": true,
    "email": "james@doe.com",
    "id": "1",
    "properties": {
        "age": 25,
        "first_name": "James",
        "last_name": "Doe",
        "sex": "M"
    },
    "tags": [
        "male",
        "yet-another-test-tag"
    ],
    "url": "/subscribers/1"
}
GET /subscribers/(str: id)

Возвращает данные подписчика.

GET /subscribers/1 HTTP/1.1
HTTP/1.0 200 OK

{
    "does_email_exist": true,
    "email": "james@doe.com",
    "id": "1",
    "properties": {
        "age": 21,
        "first_name": "James",
        "last_name": "Doe"
    },
    "tags": [
        "test-tag"
    ],
    "url": "/subscribers/1"
}
DELETE /subscribers/(str: id)

Удаляет подписчика.

PATCH /subscribers/

Выполняет операцию над группой подписчиков. Доступные операции:

  • reassign_tag — переназначает тег новой группе подписчиков (тег станет принадлежать указанным подписчикам и только им). Параметры операции должны содержать:
    • tag — тег (строка);
    • subscriber — список идентификаторов подписчиков или "all" для обозначения всех подписчиков проекта.
Json Parameters:
 
  • action (string) – имя операции
  • data (dict) – словарь, содержащий параметры операции

После данного запроса тег good станет принадлежать исключительно подписчикам с идентификаторами 1 и 192f56eb9b. Со всех остальных подписчиков проекта он будет снят:

PATCH /subscribers/ HTTP/1.1

{
    "action": "reassign_tag",
    "data": {
        "subscribers": ["1", "192f56eb9b"],
        "tag": "good"
    }
}
HTTP/1.0 204 NO CONTENT

Теги подписчиков

Информация о теге содержит следующие поля:

  • name: имя тэга;
GET /tags/?page=(int: page)&mask=(str: mask)

Возвращает постраничный список тегов подписчиков проекта.

Query Parameters:
 
  • page (int) – (опционально) номер запрашиваемой страницы
  • mask (str) – (опционально) маска для тегов

Если указана маска, метод вернет только теги, имя которых начинается с указанной маски.

GET /tags/?mask=tag HTTP/1.1
HTTP/1.0 200 OK

{
    "objects": [
        {
            "name": "tag-one"
        },
        {
            "name": "tag-two"
        }
    ],
    "total": 2,
    "page": 1,
    "pages_total": 1
}
GET /tags/(str: name)/subscribers/?page=(int: page)

Возвращает постраничный список подписчиков проекта, которым присвоен указанные тег.

Query Parameters:
 
  • page (int) – (опционально) номер запрашиваемой страницы
GET /tags/tag-one/subscribers/ HTTP/1.1
HTTP/1.0 200 OK

{
    "objects": [
        {
            "does_email_exist": true,
            "email": "james@doe.com",
            "id": "1",
            "properties": {
                "age": 21,
                "first_name": "James",
                "last_name": "Doe"
            },
            "tags": [
                "tag-one"
            ],
            "url": "/subscribers/1"
        },
        {
            "does_email_exist": true,
            "email": "john@doe.com",
            "id": "192f56eb9b",
            "properties": {},
            "tags": [
                "tag-one",
                "tag-two"
            ],
            "url": "/subscribers/192f56eb9b"
        }
    ],
    "total": 2,
    "page": 1,
    "pages_total": 1
}

Свойства подписчика

GET /subscribers/(str: id)/properties/

Возвращает словарь свойств подписчика.

GET /subscribers/1/properties/ HTTP/1.1
HTTP/1.0 200 OK

{
    "age": 25,
    "birthdate": "14.08.1990",
    "last_name": "Doe",
    "sex": "M"
}
GET /subscribers/(str: id)/properties/(string: name)

Возвращает значение свойства подписчика.

GET /subscribers/1/properties/first_name HTTP/1.1
HTTP/1.0 200 OK

{
    "value": "James"
}
POST /subscribers/(str: id)/properties/(string: name)

Изменяет значение или создаёт новое свойство подписчика.

POST /subscribers/1/properties/birthdate HTTP/1.1

{
    "value": "14.08.1990"
}
HTTP/1.0 200 OK

{
    "value": "14.08.1990"
}
DELETE /subscribers/(str: id)/properties/(string: name)

Удаляет свойство подписчика.

DELETE /subscribers/1/properties/first_name HTTP/1.1
HTTP/1.0 204 NO CONTENT

Рассылки

Информация о рассылке содержит следующие поля:

  • id: целочисленный идентификатор рассылки;
  • eta: приблизительное время в секундах, через которое закончится рассылка или null, если рассылка не исполняется в данный момент;
  • status: статус исполнения рассылки. Принимает следующие значения:
    • "FAILED", если рассылка завершена неуспешно;
    • "SUCCEEDED", если рассылка завершена успешно;
    • "ENQUEUED", если рассылка ожидает своей очереди.
  • url: resource URI.
GET /mailings/

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

GET /mailings/ HTTP/1.1
HTTP/1.0 200 OK

{
    "objects": [
        {
            "eta": null,
            "id": 13,
            "status": "FAILED",
            "url": "/mailings/13"
        },
        {
            "eta": 0,
            "id": 14,
            "status": "SUCCEEDED",
            "url": "/mailings/14"
        },
        {
            "eta": 10,
            "id": 15,
            "status": "ENQUEUED",
            "url": "/mailings/15"
        },
        {
            "eta": 20,
            "id": 16,
            "status": "ENQUEUED",
            "url": "/mailings/16"
        },
        {
            "eta": null,
            "id": 17,
            "status": "ENQUEUED",
            "url": "/mailings/17"
        }
    ],
    "total": 5,
    "page": 1,
    "pages_total": 1
}
POST /mailings/

Создаёт и выполняет рассылку.

Json Parameters:
 
  • layout_id (string) – идентификатор шаблона, который будет использован для рассылки
  • context (dict) – словарь, содержащий данные рассылки. Должен удовлетворять структуре используемого шаблона
  • target (dict) –
    словарь, задающий получателей рассылки.
    Допустимы следующие поля:
    • unsubscribe_tags: список тегов, которые буду сняты с подписчика при отписке. Поле обязательно.
    • tags_union: (по умолчанию – false) задаёт логику интерпретации списка тегов (пересечение или объединение, см. ниже);
    • tags_and_receivers_union: (по умолчанию – false) задаёт логику интерпретации наличия и списка тегов, и списка идентификаторов (пересечение или объединение, см.ниже).
    • subscribers: список идентификаторов подписчиков, явно задающий группу подписчиков;
    • tags: список тегов, задающий группу подписчиков следующим образом:
      • если tags_union имеет ложное значение – в группу входят подписчики, каждый из которых имеет все из перечисленных тегов;
      • если tags_union имеет истинное значение – в группу входят подписчики, каждый из которых имеет хотя бы один из перечисленных тегов.

    Логика интерпретации полей:

    • Если указаны поля и tags, и subscribers, то рассылка будет послана:
      • если tags_and_receivers_union имеет ложное значение – подписчикам, входящим в обе группы (пересечение);
      • если tags_and_receivers_union имеет истинное значение – подписчикам, входящим по меньше мере в одну из групп (объединение).
    • Если указано лишь одно из полей tags и subscribers, рассылка будет послана подписчика из группы, заданной этим полем.
    • Словарь должен содержать по меньшей мере одно из полей subscribers и tags.
  • attachments (list) –
    (опционально) список словарей, содержащих
    следующие поля:
    • name: имя вложения;
    • data: закодированное в BASE64 содержимое файла;
    • mimetype: MIME-тип вложения.

    Суммарный объём файлов после декодирования не должен превышать 10 МБ.

POST /mailings/ HTTP/1.1

{
    "attachments": [
        {
            "data": "SGVsbG8h",
            "mimetype": "text/plain",
            "name": "hello.txt"
        }
    ],
    "context": {
        "name": "Anton"
    },
    "layout_id": "56929c1607",
    "target": {
        "tags": [
            "test-tag",
            "male"
        ],
        "tags_and_receivers_union": true,
        "unsubscribe_tags": [
            "test-tag"
        ]
    }
}
HTTP/1.0 201 CREATED

{
    "eta": null,
    "id": 16,
    "status": "ENQUEUED",
    "url": "/mailings/16"
}
GET /mailings/(int: id)

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

GET /mailings/17 HTTP/1.1
HTTP/1.0 200 OK

{
    "eta": 20,
    "id": 17,
    "status": "ENQUEUED",
    "url": "/mailings/17"
}

Шаблоны

POST /layouts/

Создаёт шаблон с единственным вариантом.

Json Parameters:
 
  • name (string) – имя шаблона
  • markup (string) – разметка единственного варианта шаблона
  • subject_markup (string) – разметка темы шаблона
  • plaintext_markup (string) – (опционально) разметка текстовой версии шаблона
  • base (string) – (опционально) идентификатор родительского базового шаблона
  • id (string) – (опционально) идентификатор шаблона. Должен быть уникальным в рамках проекта. Будет сгенерирован системой автоматически, если не указан в запросе.
POST /layouts/ HTTP/1.1

{
    "markup": "<h1>Hello, {{ name }}!</h1><br><a href=\"{{ unsubscribe_link }}\">Unsubscribe</a>",
    "name": "Default",
    "subject_markup": "Just a hello"
}
HTTP/1.0 200 OK

{
    "id": "56929c1607"
}
DELETE /layouts/(str: id)

Удаляет шаблон.

DELETE /layouts/1 HTTP/1.1
HTTP/1.0 204 NO CONTENT
POST /base_layouts/

Создаёт базовый шаблон.

Json Parameters:
 
  • name (string) – имя
  • markup (string) – разметка
  • id (string) – (опционально) идентификатор базового шаблона. Должен быть уникальным в рамках проекта. Будет сгенерирован системой автоматически, если не указан в запросе.
POST /base_layouts/ HTTP/1.1

{
    "markup": "<div>{% block content %}<a href=\"{{ unsubscribe_link }}\">Unsubscribe</a>{% endblock %}</div>",
    "name": "Default"
}
HTTP/1.0 200 OK

{
    "id": "271f93f45e"
}
DELETE /base_layouts/(str: id)

Удаляет базовый шаблон.

DELETE //base_layouts/w7312is HTTP/1.1
HTTP/1.0 204 NO CONTENT

Отписки

Информация об отписке содержит следующие поля:

  • mailing_id: целочисленный идентификатор рассылки;

  • subscriber_id: идентификатор подписчика;

  • mailing_unsubscribe_tags: список тегов, указанных в поле unsubscribe_tags

    рассылки;

  • events: список “отписочных” событий, которые подписчик произвёл в письме

    рассылки mailing_id. События представляют собой словарь с двумя полями:

    • type: тип события:
      "action" – пользователь действительно отписался,
      "intent" – пользователь просмотрел страницу отписки.
    • created_at: время события в формате ISO;

GET /unsubscribed/?since=(str: since)&page=(int: page)

Возвращает постраничный список отписок подписчиков.

Query Parameters:
 
  • page (int) – (опционально) номер запрашиваемой страницы;
  • since (str) – (опционально) дата в формате ISO, начиная с которой перечислять события отписки;
  • subscriber_id (str) – (опционально) идентификатор подписчика, события отписки которого перечислять. По умолчанию перечисляются события всех подписчиков.
GET /unsubscribed/ HTTP/1.1
HTTP/1.0 200 OK

{
    "objects": [
        {
            "mailing_id": 1,
            "subscriber_id": "1",
            "mailing_unsubscribe_tags": ["Nigerian Spam"],
            "events": [{
                "type": "intent",
                "created_at": "2013-10-03T10:49:01"
            }]
        },
        {
            "mailing_id": 2,
            "subscriber_id": "s139sw",
            "mailing_unsubscribe_tags": ["news", "main-news"],
            "events": [{
                "type": "action",
                "created_at": "2013-13-03T13:34:51"
            }]
        }
    ],
    "total": 2,
    "page": 1,
    "pages_total": 1
}

Оглавление

Предыдущий раздел

Mailtank

Следующий раздел

Webhooks

На этой странице