API

..............................................................................................................................................................................................................................................................................................

Общая информация

API работает по протоколу HTTP.

Формат запросов: обычные HTTP GET or POST, application/x-www-form-urlencoded

Формат ответа: JSON.

Сервер-сервер запросы

Сервер-сервер API проверяет авторизацию и IP адрес клиента.

Логин и секрет передаются с помощью Basic HTTP Authorization, в заголовке Authorization

Authorization: Basic base64('login:secret')

Логин и секрет и список разрешенных IP адресов могут быть изменены в настройках проекта.

Endpoint - https://api.mailer.mail.ru/

Endpoint на сером ip - https://int.mailer.mail.ru/ (pl-i-SG_VKPLAY_STORELB)

ping https://api.mailer.mail.ru/api/watchman/ping/

Для api/v2 есть swagger. смотреть от пользователя

обе версии апи являются актуальными и равнозначными. v2 в основном дублирует возможности интерфейса.

Отправка одного Email

POST /api/mailer/send/

Отправляет Email на указанный адрес. Нельзя использовать для массовых рассылок!

Параметр	Тип	Описание
`email`	email	Email адрес пользователя
`uid`	str	Uid пользователя. Обязателен для MY.GAMES проектов
`letter`	int	ID шаблона письма
`retry`	int	Повторять отправку в случае недоступности SMTP серверов. По умолчанию 1
`send_id`	string	Любое уникальное значение в рамках проекта. Письма с одинаковым send_id не будет отправлено повторно. Send_id храниться в мейлере не меньше суток. Опционально.
`language`	string	Язык шаблона письма. Опционально.
`resolve.xxx`	string	Дополнительные параметры для фильтрации профилей. См. ниже доступные параметры
`pin.xxx`	string	Дополнительные параметры для шаблона. `pin.xxx` будет доступно в шаблоне как `{{ xxx }}`. `ЗАПРЕЩЕНО` пинить индексные поля pin.uid, pin.email, pin.phone, pin.wp_token, вместо них используйте любые другие, например pin.promo_email
`header.xxx`	string	Дополнительные параметры заголовка письма. На данный момент разрешены только заголовки "Reply-To", "Cc" и "Bcc", для добавления других, обращаться к Андрею Моисееву.
`attach.xxx`	url	Файл вложения который может быть использован в шаблоне. Например `<img src="cid:xxx"`. Файл будет скачан c указанного url и иметь content id - xxx. Content-type берется из заголовка ответа сервера. Если вложение текстовое и содержит русские буквы - надо передавать кодировку utf-8, например content_type='message/rfc822; charset=utf-8'. Таймаут на один запрос - 1 секунда. Файл будет запрошен в момент вызова api. Пока, суммарное ограничение на attach/attachment - 4 штуки.
`attachment.xxx`	url	Файл вложения. Файл будет скачан c указанного url и иметь имя - xxx. Content-type берется из заголовка ответа сервера. Если вложение текстовое и содержит русские буквы - надо передавать кодировку utf-8, например content_type='message/rfc822; charset=utf-8'. Таймаут на один запрос - 1 секунда. Файл будет запрошен в момент вызова api. Пока, суммарное ограничение на attach/attachment - 4 штуки.

Успешная отправка

{
    "sent": 1,
    "retry": 0,
    "status": "ok"
}

Письмо добавлено в очередь

{
    "sent": 0,
    "retry": 1,
    "status": "ok"
}

Язык шаблона не найден

{
  "args_errors": {
    "language": [
      "Bad language. Received: 'en'. Available: ['ru']"
    ]
  },
  "status": "fail",
  "code": 3000,
  "msg": "incorrect arguments"
}

Письмо с таким send_id уже отправляется

{
    "status": "fail",
    "msg": "send in progress",
    "code": 3017,
    "current_status": "W"
}

Письмо с таким send_id уже отпправлено

{
    "status": "fail",
    "msg": "already sent",
    "code": 3016,
    "sent_at": "1548920365"
}

Флаги и параметры для resolve.xxx

not_check_spam_quarantine - Bool. Не проверять в спам-карантине, default=True
send_to_corp - Рассылать на @corp.mail.ru, default= True
not_check_subscription - Bool. Не проверять подписавшихся / отписавшихся. Это письмо будет отправлено любому пользователю, независимо от его подписки, default= True
not_check_sent_quarantine - Bool. Игнорировать политику отправки ("Не более N сообщений в M дней на юзера"). Например "Не более 2 сообщений в 15 дней на юзера". N и M указаны в настройках проекта, default= True
min_send_interval - Integer. Не слать пользователю письмо с тем же ID в течении N секунд, default=0

Счетчики в поле Stats

viewed - всего email просмотрено
selected - выбрано для отправки
stop_noaddress - у профиля нет email (может быть когда вместо email передается uid)
stop_gdpr - пользователь удален по GDPR
stop_unsubscr - пользователь отписан (по умолчанию не проверяется для API рассылок)
stop_nonexistent - пришел hard bounce
stop_inactive - swa считает что пользователь disabled или не существует
stop_sendlog_added профиль попал в карантин: непрошедший политику отправки проекта

Пример curl

curl --request POST 'https://api.mailer.mail.ru/api/mailer/send/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic ***' \
--data-urlencode 'email=user@mail.ru' \
--data-urlencode 'letter=1234' \
--data-urlencode 'pin.xxx=value'

Отправка одного SMS

POST /api/sms/send/

Параметр	Тип	Описание
`phone`	phone	Номер телефона
`message`	int	ID СМС сообщения для отправки
`pin.xxx`	string	Дополнительные параметры для шаблона. `pin.xxx` будет доступно в шаблоне как `{{ xxx }}`

Успешная отправка

{
    "sent": 1,
    "status": "ok",
}

Отправка не удалась

{
    "sent": 0,
    "status": "fail",
}

Работа с профилям

Пользователи могут быть идентифицированы с помощью одного из трех полей * uid - ID пользователя в проекте * email - его Email адрес * phone - его телефон, если есть

Как минимум один из этих параметров должен быть передан в вызовы связанные с профилями.

Создание / обновление пользователя

POST /api/profiles/update/

Создает нового или обновляет существующего пользователя на основании переданных полей.

Все не-индексные поля должны быть переданы через параметры, начинающиеся с pin.

Все поля должны быть предварительно объявлены через Web интерфейс в настройках проекта. Все необъявленные поля будут проигнорированы.

Обновление полей профиля может привести к запуску тригерных рассылок.

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`pin.xxx`		Произвольные поля профиля специфичные для проекта
`unpin.xxx`		Очищает указанные поля профиля. Переданное значение с этим полем будет проигнорированно

Успешное обновление

{
    "status": "ok"
}

Системные поля профиля пользователя

Внутреннее название	Название	Тип данных	Возможность обновления через API
`subscribed_at`	Дата подписки (single opt-in)	Дата и время	Нет
`confirmed_at`	Дата подтверждения Email (double opt-in)	Дата и время	Нет
`unsubscribed_at`	Дата отписки	Дата и время	Нет
`subscribed_categories`	Категории подписки	JSON	Нет
`spam_reported_at`	Дата добавления в спам-карантин	Дата и время	Нет
`bounce_error`	Последняя bounce ошибка	Строка	Нет
`bounce_at`	Дата последней bounce ошибки	Дата и время	Нет
`blacklisted_at`	Дата добавления в блэклист	Дата и время	Нет
`lang`	Язык пользователя	Строка	Да
`gender`	Пол	Строка	Да
`birthday`	День рождения	Дата и время	Да
`email_verified`	Email подтвержден	Флаг	Да
`gcnotif_unsubscribe_at`	Дата отписки от нотификаций	Дата и время	Нет
`uid`	ID пользователя	Строка	Да
`email`	Email	Строка	Да
`phone`	Номер телефона	Строка	Да
`wp_token`	WebPush token	Строка	Да

Получение профиля

GET /api/profiles/get/

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально

Профиль найден

{
    "status": "ok",
    "profile": {
        "uid": 24234,
        "email": "user@mail.ru",
        "level": 33,
        "something_else": "data"
    }
}

Получение всех профилей по email. Для MY.GAMES проектов

GET /api/profiles/get_all/

Параметр	Тип	Описание
`email`	email	Email пользователя.

Профиль найден

{
    "status": "ok",
    "profiles": [{
        "uid": 24234,
        "email": "user@mail.ru",
        "level": 33,
        "something_else": "data"
    },
    {
        "uid": 264563,
        "email": "user@mail.ru",
        "level": 3,
        "something_else": "other_data"
    }]
}

Верификация профиля

POST /api/profiles/verify/

Отмечает пользователя как верифицированного.

Лучше использовать микроформат см (https://admin.mailer.mail.ru/docs/view/templates/)

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально

Подтверждение получения маркетинговых рассылок профиля

POST /api/profiles/confirm/

Отмечает пользователя как согласного для получения маркетинговых рассылок. Лучше использовать микроформат см (https://admin.mailer.mail.ru/docs/view/templates/)

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`not_subscribe`	bool	Не подписывать, в случае отсутствия подписки
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Подписка профиля

POST /api/profiles/subscribe/

POST /api/profiles/subscribe/{{token}}/- по безопасной ссылке

Отмечает пользователя как подписанного на все категории проекта. Список категорий может быть изменен в настройuках проекта в Web интерфейсе mailer. Проект НЕ должен подписывать пользователя на рассылки без явного согласия пользователя. EULA и прочие юридические документы таковым согласием не считаются. Проект НЕ должен подписывать пользователя на все категории, если он подписался только на некоторые. Ответственность за такие рассылки несет проект.

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`lang`	string	Язык который проставится в профиль. Формат: ru,en,fr или en_US,ru_RU,fr_FR. Опционально
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Профиль подписан

{
    "status": "ok",
    "profile_categories": [1, 2, 3, 4, 5],
}

Подписка профиля на одну категорию

POST /api/profiles/subscribe_category/

Добавляет только указанную категорию в подписки

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`category`	int	Номер категории на которую подписывают
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

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

{
    "status": "ok"
    "profile_categories": [1, 2, 5],
}

Отписка профиля

POST /api/profiles/unsubscribe/

Помечает пользователя как отписанного от всех категорий проекта. Отписанные пользователи не будут получать Email от проекта (если обход этого правила не задан явно).

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Пользователь отписан

{
    "status": "ok"
    "profile_categories": [],
}

Отписка профиля от одной категории

POST /api/profiles/unsubscribe_category/

Удаляет только указанную категорию из подпискок

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`category`	int	Номер категории от которой отписывают
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

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

{
    "status": "ok"
    "profile_categories": [1, 2],
}

Отписка профиля пользователя по безопасной ссылке

POST /api/profiles/unsubscribe/{{token}}/

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Пользователь отписан

{
    "status": "ok"
    "profile_categories": [],
}

Смена категорий пользователя

POST /api/profiles/set_subscriptions/

Устанавливает новый список категорий, на которые подписан пользователь. Если список категорий пуст, это работает так же как отписка пользователя.

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`categories`	[]int	Список ID категорий на который пользователь подписан
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Пример: categories=1&categories=4&categories=6

Настройки изменены

{
    "status": "ok",
    "profile_categories": [1, 4, 6],
}

Смена категорий пользователя по безопасной ссылке

POST /api/profiles/set_link_subscriptions/{{token}}/

Параметр	Тип	Описание
`profile_categories`	[]int	Список ID категорий на который пользователь подписан
`ip`	ip	Ip пользователя для gdpr лога при сервер-сервер запросах. Опционально
`agent`	string	User-agent пользователя для gdpr лога при сервер-сервер запросах. Опционально

Пример: profile_categories=1&profile_categories=4&profile_categories=6

Настройки изменены

{
    "status": "ok",
    "profile_categories": [1, 4, 6],
}

Получение категорий пользователя

GET /api/profiles/get_subscriptions/

Возвращает категории на которые подписан пользователь. Так же возвращает информацию о всех возможных категориях проекта.

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально
`lang`	string	Желаемая локализация названий категорий. Опционально. Например: de_DE

Получение категорий пользователя по безопасной ссылке

GET /api/profiles/get_link_subscriptions/{{token}}/

Настройки пользователя

{
    "status": "ok",
    "profile_categories": [1, 3],
    "project": {
       "name": "The Project",
       "logo": "https://mailer.mail.ru/path/to/logo.png",
       "categories": [
           {
               "id": 1,
               "title": "Security Notifications",
               "description": "Important messages about your account",
           },
           {
               "id": 2,
               "title": "News and promos",
               "description": "Information about new products",
           },
           {
               "id": 3,
               "title": "Messages from other users",
               "description": "Notifications about personal messages from other users",
           },
       ]
    },
}

POST /api/profiles/void/

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

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально

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

Параметр	Тип	Описание
`ext_ids`	[]str	External id проекта. Опционально

Пример: email=test@mail.ru&ext_ids=project1.my.com&ext_ids=project2.my.com

Пользователь удален и добавлен в GDPR карантин

{
    "status": "ok"
}

Удаление пользователя

POST /api/profiles/delete/

Не удаляйте пользователей без КРАЙНЕЙ необходимости!

Удаляет пользователя из рассыльщика. Удаляет всю историю и карантины.

Параметр	Тип	Описание
`uid`	string	ID пользователя в проекте. Опционально
`phone`	phone	Телефон пользователя. Опционально
`email`	email	Email пользователя. Опционально

Пример: email=test@mail.ru

Пользователь удален

{
    "status": "ok"
}

Пользователь не найден

{
  "status": "fail",
  "code": 3008,
  "msg": "no such profile"
}

Отправка double-opt-in письма по sezam_id

GET /api/mailer/send_verify/

Параметр	Тип	Описание
`email`	email	Email пользователя
`ext_id`	int/str	Идентификатор проекта

Удачная отправка

{
    "status": "ok",
    "letter_id": 1234
}

Коды ошибок

Код ошибки	Описание
3000	Некорректные параметры
3001	Доступ запрещен, нет заголовка `Authorization`
3001	Доступ запрещен, неверный логин или секрет
3001	Доступ запрещен, IP нет в списке разрешенных
3002	Письмо, СМС или ИЦ уведомление не найдено
3003	Слишком много адресов
3004	Проект не найден
3005	Нет доступа к данному объекту
3006	Не удалось отправить сообщение
3007	Некорректные поля профиля, например неправильная дата для полей-дат
3008	Профиль не найден
3013	Метод API не поддерживается
3014	Превышена частота вызовов для данной операции
3015	Сообщение не было отправлено - пользователь не прошел фильтры
3016	Сообщение не было отправлено - сообщение с переданным send_id уже отправлялось
3017	Сообщение не было отправлено - сообщение с переданным send_id в процессе отравки
3018	Некорректный JWT токен
3019	Шаблон письма/нотифа/смс/пуша находится в архиве
3020	Политика отправки проекта не поддерживает данный метод

API

Содержание

Общая информация

обе версии апи являются актуальными и равнозначными. v2 в основном дублирует возможности интерфейса.

Отправка одного Email

Успешная отправка

Письмо добавлено в очередь

Язык шаблона не найден

Письмо с таким send_id уже отправляется

Письмо с таким send_id уже отпправлено

Флаги и параметры для resolve.xxx

Счетчики в поле Stats

Пример curl

Отправка одного SMS

Успешная отправка

Отправка не удалась

Работа с профилям

Создание / обновление пользователя

Успешное обновление

Системные поля профиля пользователя

Получение профиля

Профиль найден

Получение всех профилей по email. Для MY.GAMES проектов

Профиль найден

Верификация профиля

Подтверждение получения маркетинговых рассылок профиля

Подписка профиля

Профиль подписан

Подписка профиля на одну категорию

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

Отписка профиля

Пользователь отписан

Отписка профиля от одной категории

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

Отписка профиля пользователя по безопасной ссылке

Пользователь отписан

Смена категорий пользователя

Настройки изменены

Смена категорий пользователя по безопасной ссылке

Настройки изменены

Получение категорий пользователя

Получение категорий пользователя по безопасной ссылке

Настройки пользователя

Удаление пользователя и добавление в GDPR карантин

Пользователь удален и добавлен в GDPR карантин

Удаление пользователя

Пользователь удален

Пользователь не найден

Отправка double-opt-in письма по sezam_id

Удачная отправка

Коды ошибок