Download OpenAPI specification:
Генерирует новую пару токенов:
token имеет короткий срок жизни и нужен для авторизации API запросов.refresh_token имеет более длинный срок жизни и нужен для обновления пары.Пример запроса для получения пары.
| user required | string (user) Имя пользователя, которое можно найти в настройках домена в разделе Токены. |
| token required | string <uuid> (password) Токен, который можно найти в настройках домена в разделе Токены. |
| white_address required | string (white_address) Адрес, с которого будет отправляться почта. Его можно найти в настройках домена в разделе Адреса. |
{- "user": "robot",
- "token": "b8024fdb-2be9-4fc2-8032-6c8f6959ffb9",
- "white_address": "robot@mail-king.ru"
}{- "token": "b8024fdb-2be9-4fc2-8032-6c8f6959ffb9",
- "refresh_token": "27e47104-8bee-456a-b1f2-156985a89bb3",
- "token_expires_at": "2023-05-25T20:48:13.814+03:00",
- "refresh_token_expires_at": "2023-05-25T20:48:13.814+03:00"
}Перевыпускает новую пару токенов по рефреш токену из исходной пары.
Пример запроса для обновления пары.
| refresh_token required | string <uuid> (refresh_token) Токен, необходимый для обновления пары. |
{- "refresh_token": "b8024fdb-2be9-4fc2-8032-6c8f6959ffb9"
}{- "token": "b8024fdb-2be9-4fc2-8032-6c8f6959ffb9",
- "refresh_token": "27e47104-8bee-456a-b1f2-156985a89bb3",
- "token_expires_at": "2023-05-25T20:48:13.814+03:00",
- "refresh_token_expires_at": "2023-05-25T20:48:13.814+03:00"
}Позволяет выгрузить отчет по отправленным письмам. Поддерживается два формата отчетов:
simple – базовый, содержащий в себе статус письма и дату отправки.full – полный, содержащий в себе базовую информацию, а также расширенные данные об ошибке (если письмо не доставлено) и события (открытия, переходы и отписки).Ограничения:
По-умолчанию выгружается базовая версия отчета.
Пример запроса для выгрузки отчета.
| uuids required | Array of strings <uuid> (uuids) [ items <uuid > ] Список UUID писем. |
| format | string (format) Default: "simple" Enum: "simple" "full" Формат отчета. |
{- "uuids": [
- "e5438584-85d9-4ba0-963c-79808edeb72b",
- "852ef987-bcb6-4bee-8d80-d16e7909dfc0"
]
}{- "status": "ok",
- "data": {
- "emails": {
- "8ff747f5-032d-4381-920b-10c39a972a4d": {
- "out_datetime": "2023-03-08T13:05:09+03:00",
- "status": "delivered"
}
}
}
}Разбивает исходное письмо на N получателей, указанных в параметрах to, cc и bcc, и отправляет каждому из них письмо.
Ограничения:
| Idempotence-Key | string Ключ идемпотентности, исключающий повторную обработку запроса с такими же параметрами. Исключает повторное выполнение запросов с таким же ключом на протяжении следующих N секунд. |
| Idempotence-Ttl | integer [ 1000 .. 3600000 ] Default: 60000 Время жизни ключа идемпотентности (в миллисекундах). |
| Content-Encoding | string Value: "gzip" Позволяет передавать содержимое запроса в сжатом виде. Важно: работает только в паре с |
Пример запроса для отправки письма.
| subject | string (subject) Тема письма. |
| html required | string <html> (html) HTML часть письма. Необходимо заполнить либо это поле, либо |
| text required | string (text) Текстовая часть письма. Необходимо заполнить либо это поле, либо |
| reply_to | string (reply_to) Ответный адрес. |
| from_name | string (from_name) [ 1 .. 30 ] characters Имя отправителя, которое пользователь увидит в почтовом клиенте. Имя, указанное в запросе, имеет больший приоритет над именем, указанным в настройках адреса в личном кабинете. |
| to[] required | Array of strings <email> (to) [ items <email > ] Список почтовых адресов, на которые нужно отправить письмо. |
| cc[] | string (cc) Список почтовых адресов, которые нужно добавить в открытую копию. |
| bcc[] | string (bcc) Список почтовых адресов, которые нужно добавить в скрытую копию. |
| attachments[] | Array of file (attachments[]) Список вложений к письму. |
Array of objects (headers) <= 25 items Заголовки письма. | |
| callback_url | string (callback_url) Ссылка, на которую будет отправлен коллбэк с информацией по письму. Перед использованием необходимо настроить подсистему коллбэков в личном кабинете. |
{ "subject": "Тема письма.", "from_name": "mailking", "html": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"><title>title</title><link rel=\"stylesheet\" href=\"style.css\"><script src=\"script.js\"></script></head><body></body></html>", "to[]": [ "Sergey <sergey@mail-king.ru>", "mikhail@mail-king.ru", "<konstantin@mail-king.ru>" ] }
{- "status": "ok",
- "data": {
- "delivered": {
- "sergey@mail-king.ru": "84df2ae9-71a6-4af3-b049-2f9c1d1f8ab6"
}
}
}Разбивает каждое письмо из списка на N получателей, указанных в параметрах to, cc и bcc, и отправляет каждому из них письмо.
Ограничения:
| Idempotence-Key | string Ключ идемпотентности, исключающий повторную обработку запроса с такими же параметрами. Исключает повторное выполнение запросов с таким же ключом на протяжении следующих N секунд. |
| Idempotence-Ttl | integer [ 1000 .. 3600000 ] Default: 60000 Время жизни ключа идемпотентности (в миллисекундах). |
| Content-Encoding | string Value: "gzip" Позволяет передавать содержимое запроса в сжатом виде. Важно: работает только в паре с |
Пример запроса для отправки письма.
required | Array of objects Список писем. |
{- "emails": [
- {
- "id": "1",
- "subject": "Тема письма.",
- "from_name": "mailking",
- "html": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"><title>title</title><link rel=\"stylesheet\" href=\"style.css\"><script src=\"script.js\"></script></head><body></body></html>",
- "to": [
- "Sergey <sergey@mail-king.ru>",
- "mikhail@mail-king.ru",
- "<konstantin@mail-king.ru>"
], - "attachments": [
- {
- "name": "filename.txt",
- "content_type": "text/plain",
- "content": "c29tZSBjb250ZW50"
}
], - "headers": [
- {
- "name": "X-Custom-Header",
- "value": "Custom value"
}, - {
- "name": "X-Other-Custom-Header",
- "value": "Не ASCII заголовок"
}
]
}
]
}{- "status": "ok",
- "data": {
- "1": {
- "delivered": {
- "sergey@mail-king.ru": "84df2ae9-71a6-4af3-b049-2f9c1d1f8ab6"
}
}, - "2": {
- "delivered": {
- "irina@mail-king.ru": "b0aff206-e9df-4e07-a714-5465ad7cc47c"
}
}
}
}Отличается от транзакционных писем тем, что тему и содержимое письма берет из шаблона.
Помимо вложений, содержащихся в шаблоне, в запросе можно указать дополнительные.
В случае если название файла в запросе совпадает с названием файла в шаблоне – будет использован файл из запроса.
Разбивает исходное письмо на N получателей, указанных в параметрах to, cc и bcc, и отправляет каждому из них письмо.
Ограничения:
| id required | string Идентификатор шаблона. Его можно найти в разделе "Шаблоны". |
| Idempotence-Key | string Ключ идемпотентности, исключающий повторную обработку запроса с такими же параметрами. Исключает повторное выполнение запросов с таким же ключом на протяжении следующих N секунд. |
| Idempotence-Ttl | integer [ 1000 .. 3600000 ] Default: 60000 Время жизни ключа идемпотентности (в миллисекундах). |
| Content-Encoding | string Value: "gzip" Позволяет передавать содержимое запроса в сжатом виде. Важно: работает только в паре с |
Пример запроса для отправки письма.
| reply_to | string (reply_to) Ответный адрес. |
| from_name | string (from_name) [ 1 .. 30 ] characters Имя отправителя, которое пользователь увидит в почтовом клиенте. Имя, указанное в запросе, имеет больший приоритет над именем, указанным в настройках адреса в личном кабинете. |
| to[] required | Array of strings <email> (to) [ items <email > ] Список почтовых адресов, на которые нужно отправить письмо. |
| cc[] | string (cc) Список почтовых адресов, которые нужно добавить в открытую копию. |
| bcc[] | string (bcc) Список почтовых адресов, которые нужно добавить в скрытую копию. |
| attachments[] | Array of file (attachments[]) Список вложений к письму. |
| variables | object (variables) Переменные, которые нужно вставить в шаблон. Не поддерживает вложенные переменные. Пример корректного объекта: { "name": "Сергей" } Пример некорректного объекта: { "user": { "name": "Сергей" } } |
Array of objects (headers) <= 25 items Заголовки письма. | |
| callback_url | string (callback_url) Ссылка, на которую будет отправлен коллбэк с информацией по письму. Перед использованием необходимо настроить подсистему коллбэков в личном кабинете. |
{ "to[]": [ "Sergey <sergey@mail-king.ru>", "mikhail@mail-king.ru", "<konstantin@mail-king.ru>" ] }
{- "status": "ok",
- "data": {
- "delivered": {
- "sergey@mail-king.ru": "84df2ae9-71a6-4af3-b049-2f9c1d1f8ab6"
}
}
}Отличается от транзакционных писем тем, что тема и содержимое для писем берется из шаблона.
Разбивает каждое письмо из списка на N получателей, указанных в параметрах to, cc и bcc, и отправляет каждому из них письмо.
Ограничения:
| id required | string Идентификатор шаблона. Его можно найти в разделе "Шаблоны". |
| Idempotence-Key | string Ключ идемпотентности, исключающий повторную обработку запроса с такими же параметрами. Исключает повторное выполнение запросов с таким же ключом на протяжении следующих N секунд. |
| Idempotence-Ttl | integer [ 1000 .. 3600000 ] Default: 60000 Время жизни ключа идемпотентности (в миллисекундах). |
| Content-Encoding | string Value: "gzip" Позволяет передавать содержимое запроса в сжатом виде. Важно: работает только в паре с |
Пример запроса для отправки письма.
required | Array of objects Список писем. |
{- "emails": [
- {
- "id": "1",
- "from_name": "mailking",
- "to": [
- "Sergey <sergey@mail-king.ru>",
- "mikhail@mail-king.ru",
- "<konstantin@mail-king.ru>"
], - "attachments": [
- {
- "name": "filename.txt",
- "content_type": "text/plain",
- "content": "c29tZSBjb250ZW50"
}
]
}
]
}{- "status": "ok",
- "data": {
- "1": {
- "delivered": {
- "sergey@mail-king.ru": "84df2ae9-71a6-4af3-b049-2f9c1d1f8ab6"
}
}, - "2": {
- "delivered": {
- "irina@mail-king.ru": "b0aff206-e9df-4e07-a714-5465ad7cc47c"
}
}
}
}Создает шаблон для письма. Предоставляет возможность добавить к шаблону вложения и встречу.
Пример запроса для создания шаблона через API.
| name required | string (name) Имя шаблона, которое должно быть уникальным в рамках домена. |
| subject required | string (subject) Тема письма. |
| body required | string (body) Тело шаблона. |
Array of objects (schemas-attachments) Список вложений к шаблону. | |
object (meeting) Встреча. |
{- "name": "default_template",
- "subject": "Стандартный шаблон",
- "body": "<div></div>"
}{- "status": "ok"
}Получение списка шаблонов по фильтрам.
| name | string Выводит все шаблоны, в названии которых содержится указанная строка. |
| subject | string Выводит все шаблоны, в теме которых содержится указанная строка. |
| more_attachments_count | numeric Выводит все шаблоны, в которых количество вложений больше или равно указанному значению. |
| less_attachments_count | numeric Выводит все шаблоны, в которых количество вложений меньше указанного значения. |
| more_size | numeric Выводит все шаблоны, в которых размер в Мб больше или равен указанному значению. |
| less_size | numeric Выводит все шаблоны, в которых размер в Мб меньше указанного значения. |
| sort | string Enum: "name" "subject" "attachments_count" "size" "created_at" "updated_at" Сортирует список по указанному полю. |
| sort_dir | string Enum: "asc" "desc" Сортирует список в указанном направлении. |
{- "status": "ok",
- "data": [
- {
- "name": "default_template",
- "subject": "Стандартный шаблон",
- "body": "<div></div>",
- "created_at": "2024-01-20T14:00:30.0+03:00",
- "attachments": [
- {
- "name": "filename.txt",
- "size": 100
}
], - "meeting": {
- "summary": "daily meeting",
- "description": "Стэнд Ап команды",
- "date_start": "2024-01-20T14:00:30.0+03:00",
- "date_end": "2024-01-20T15:00:30.0+03:00",
- "location": "meeting room",
- "url": "meeting.com/daily"
}
}, - {
- "name": "default_template_new",
- "subject": "Новый стандартный шаблон",
- "body": "<div></div>",
- "created_at": "2024-01-20T14:00:30.0+03:00",
- "attachments": [
- {
- "name": "filename.txt",
- "size": 100
}
], - "meeting": {
- "summary": "daily meeting",
- "description": "Стэнд Ап команды",
- "date_start": "2024-01-20T14:00:30.0+03:00",
- "date_end": "2024-01-20T15:00:30.0+03:00",
- "location": "meeting room",
- "url": "meeting.com/daily"
}
}
]
}Обновляет шаблон для письма. Предоставляет возможность обновить поля шаблона и перезаписать вложения и встречу.
Важно: обновление встречи или списка вложений полностью перезаписывает предыдущие значения.
| name required | string Идентификатор шаблона, так же его имя. Его можно найти в разделе "Шаблоны". |
Пример запроса для обновления шаблона через API.
| name | string (name) Имя шаблона, которое должно быть уникальным в рамках домена. |
| subject | string (subject) Тема письма. |
| body | string (body) Тело шаблона. |
Array of objects (schemas-attachments) Список вложений к шаблону. | |
object (meeting) Встреча. |
{- "name": "default_template"
}{- "status": "ok"
}Получение шаблона по имени.
| name required | string Идентификатор шаблона, так же его имя. Его можно найти в разделе "Шаблоны". |
{- "status": "ok",
- "data": {
- "name": "default_template",
- "subject": "Стандартный шаблон",
- "body": "<div></div>",
- "created_at": "2024-01-20T14:00:30.0+03:00",
- "attachments": [
- {
- "name": "filename.txt",
- "size": 100
}
], - "meeting": {
- "summary": "daily meeting",
- "description": "Стэнд Ап команды",
- "date_start": "2024-01-20T14:00:30.0+03:00",
- "date_end": "2024-01-20T15:00:30.0+03:00",
- "location": "meeting room",
- "url": "meeting.com/daily"
}
}
}Удаляет из шаблона все вложения. Не затрагивает встречу.
| name required | string Идентификатор шаблона, так же его имя. Его можно найти в разделе "Шаблоны". |
{- "status": "ok"
}Удаляет из шаблона встречу. Не затрагивает вложения.
| name required | string Идентификатор шаблона, так же его имя. Его можно найти в разделе "Шаблоны". |
{- "status": "ok"
}Если вы настроили коллбэки на своем домене, то на указанный вами URL будут приходить запросы с информацией о следующих событиях, каждому из которых соответствует определенное значение поля event_kind:
mail.deliver.mail.open.mail.links.open.mail.unsubscribe.События mail.open, mail.links.open и mail.unsubscribe отправляются только один раз. Повторные события будут проигнорированы.
Все запросы подписываются с помощью токена, указанного в настройках коллбэка. Чтобы проверить подпись на вашей стороне нужно:
<token><timestamp>.
Пример полученной строки – f8e99e2b-99e4-492d-819b-585af12828af1685028302314.X-Checksum-Sha1.Список IP адресов, с которых мы отправляем запросы:
Пример отправляемого нами запроса.
| timestamp required | int (timestamp) Дата и время формирования события (в миллисекундах). |
required | Array of delivery (object) or event (object) Список событий. |
{- "timestamp": 1676452827434,
- "events": [
- {
- "timestamp": 1676452827434,
- "message_id": "123e4567-e89b-12d3-a456-426614174000",
- "event_kind": "mail.deliver",
- "status": "delivered",
- "kind": "outbound"
}, - {
- "timestamp": 1676452827434,
- "message_id": "123e4567-e89b-12d3-a456-426614174000",
- "status": "rejected",
- "event_kind": "mail.deliver",
- "kind": "outbound",
- "error_code": "500",
- "error_enhanced_code": "5.0.0",
- "error_kind": "user_not_found",
- "error_message": "non-local sender verification failed"
}, - {
- "timestamp": 1676452827434,
- "message_id": "123e4567-e89b-12d3-a456-426614174000",
- "event_kind": "mail.open"
}, - {
- "timestamp": 1676452827434,
- "message_id": "123e4567-e89b-12d3-a456-426614174000",
- "event_kind": "mail.links.open"
}, - {
- "timestamp": 1676452827434,
- "message_id": "123e4567-e89b-12d3-a456-426614174000",
- "event_kind": "mail.unsubscribe"
}
]
}Если вы добавили хотя бы один шаблон адреса на своем домене, то на указанный в этом шаблоне URL будут приходить запросы со всей входящей почтой, адресуемой на этот почтовый ящик.
Все запросы подписываются с помощью токена, указанного в настройках шаблона. Чтобы проверить подпись на вашей стороне нужно:
<token><timestamp>.
Пример полученной строки – f8e99e2b-99e4-492d-819b-585af12828af1685028302314.X-Checksum-Sha1.Список IP адресов, с которых мы отправляем запросы:
Пример отправляемого нами запроса.
| t required | int (schemas-timestamp) Дата и время формирования запроса (в миллисекундах). |
required | object (letter) Письмо. |
{- "t": 1676452827434,
- "letter": {
- "envelope_from": "sergey@mail-king.ru",
- "envelope_to": "inbound@mail-king.ru",
- "letter_to": [
- "inbound@mail-king.ru"
], - "letter_from": [
- "sergey@mail-king.ru"
], - "cc": [ ],
- "bcc": [ ],
- "subject": "Тема входящего письма.",
- "html": "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"utf-8\"><title>title</title><link rel=\"stylesheet\" href=\"style.css\"><script src=\"script.js\"></script></head><body></body></html>",
- "text": "Текстовая часть письма",
- "attachments": [
- {
- "filename": "plain.txt",
- "content_type": "text/plain",
- "content": "Привет!"
}
], - "embedded_files": [
- {
- "cid": "plain.txt",
- "content_type": "text/plain",
- "content": "Привет!"
}
]
}
}