Скидки до 40%
", "track_opens": "Y" } } } } } }, "/campaigns/{campaign_id}": { "get": { "operationId": "get-campaign", "summary": "Одна рассылка", "tags": [ "Рассылки" ], "description": "Возвращает рассылку целиком, включая HTML- и текстовую версии письма.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Рассылки с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#get-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "merge_json", "in": "query", "required": false, "description": "Отдавать вложенные структуры как JSON. Признак: передайте 1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 501233, "name": "Весенняя распродажа", "subject": "Скидки до 40%", "from_name": "Ромашка", "from_email": "news@example.ru", "list_id": "128341", "status": "SENT", "track_opens": "Y", "track_clicks": "Y", "delivery_time": "2026-04-05 10:00:00", "html": "Скидки
отписаться", "plain_text": "Скидки. Отписаться: %ОТПИСАТЬСЯ%" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update-campaign", "summary": "Изменить и запустить рассылку", "tags": [ "Рассылки" ], "description": "Меняет черновик и — через параметр `status` — запускает отправку.\n\nИзменять можно рассылки в статусах `DRAFT`, `SCHEDULE`, `TRIGGER` и `TEMPLATE`. Уже отправляющуюся рассылку изменить нельзя.\n\n> **Примечание.** **Как отправить рассылку.** Передайте `status=MODERATING`, чтобы письмо ушло сразу после модерации, либо `status=SCHEDULE` вместе с `delivery_time`, чтобы запланировать отправку. Перед запуском проверяются тема, отправитель, наличие текста письма и [ссылки отписки](https://dashamail.ru/api/campaigns/#unsub-link).\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `status` | string | Новый статус. Запуск отправки — `MODERATING` или `SCHEDULE`. Допустимые значения: `DRAFT`, `MODERATING`, `SCHEDULE`, `TEMPLATE`. |\n| `delivery_time` | datetime | Время запланированной отправки. Обязателен при `status=SCHEDULE`. |\n| `subject` | string | Тема письма. |\n| `from_email` | string | Адрес отправителя. |\n| `from_name` | string | Имя отправителя. |\n| `name` | string | Внутреннее название. |\n| `list_id` | integer | JSON-строка | Сменить адресную базу или набор баз. |\n| `html` | string | HTML-версия письма. |\n| `plain_text` | string | Текстовая версия письма. |\n| `esegment` | JSON-строка | Условия сегментации. |\n| `track_opens` | string | Отслеживание открытий. Допустимые значения: `Y`, `N`. |\n| `track_clicks` | string | Отслеживание кликов. Допустимые значения: `Y`, `N`. |\n| `stat_domain` | string | Домен статистики. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет либо её статус не допускает изменений |\n| `409` | `21` | Рассылка уже отправляется |\n| `500` | `20` | Недопустимое значение `status` |\n| `500` | `13` | При `SCHEDULE` не задан `delivery_time` |\n| `500` | `14` | Не задана тема письма |\n| `500` | `15` | Не задано имя отправителя |\n| `500` | `16` | Не задан адрес отправителя |\n| `500` | `17` | Нет ни HTML-, ни текстовой версии |\n| `500` | `18` | В HTML нет ссылки отписки с `id=\"unsub_link\"` |\n| `500` | `19` | В тексте нет подстановки `%ОТПИСАТЬСЯ%` |\n| `402` | `25` | Недостаточно средств на балансе |\n| `403` | `30` | Отправка заблокирована по подозрению в спаме |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#update-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DRAFT", "MODERATING", "SCHEDULE", "TEMPLATE" ], "description": "Новый статус. Запуск отправки — `MODERATING` или `SCHEDULE`." }, "delivery_time": { "type": "string", "example": "2026-03-14 11:02:41", "description": "Время запланированной отправки. Обязателен при `status=SCHEDULE`." }, "subject": { "type": "string", "description": "Тема письма." }, "from_email": { "type": "string", "description": "Адрес отправителя." }, "from_name": { "type": "string", "description": "Имя отправителя." }, "name": { "type": "string", "description": "Внутреннее название." }, "list_id": { "type": "string", "description": "Сменить адресную базу или набор баз." }, "html": { "type": "string", "description": "HTML-версия письма." }, "plain_text": { "type": "string", "description": "Текстовая версия письма." }, "esegment": { "type": "string", "description": "Условия сегментации." }, "track_opens": { "type": "string", "enum": [ "Y", "N" ], "description": "Отслеживание открытий." }, "track_clicks": { "type": "string", "enum": [ "Y", "N" ], "description": "Отслеживание кликов." }, "stat_domain": { "type": "string", "description": "Домен статистики." } }, "additionalProperties": true }, "example": { "status": "SCHEDULE", "delivery_time": "2026-05-01 10:00:00" } } } } }, "delete": { "operationId": "delete-campaign", "summary": "Удалить рассылку", "tags": [ "Рассылки" ], "description": "Помечает рассылку удалённой. Статистика по уже отправленным письмам сохраняется.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#delete-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{campaign_id}/copy": { "post": { "operationId": "copy-campaign", "summary": "Скопировать рассылку", "tags": [ "Рассылки" ], "description": "Создаёт копию рассылки вместе с вёрсткой. Копия отправленной или заблокированной рассылки всегда получает статус `DRAFT`.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `name` | string | Название копии. По умолчанию совпадает с исходным. |\n| `client_id` | integer | Создать копию в аккаунте клиента. Доступно партнёрским аккаунтам. |\n\n**Что возвращается**\n\nИдентификатор созданной копии.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Исходной рассылки нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#copy-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор исходной рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "campaign_id": 501240 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Название копии. По умолчанию совпадает с исходным." }, "client_id": { "type": "integer", "description": "Создать копию в аккаунте клиента. Доступно партнёрским аккаунтам." } }, "additionalProperties": true }, "example": { "name": "Весенняя распродажа — повтор" } } } } } }, "/campaigns/{campaign_id}/pause": { "post": { "operationId": "pause-campaign", "summary": "Поставить отправку на паузу", "tags": [ "Рассылки" ], "description": "Приостанавливает идущую рассылку. Уже отправленные письма не отзываются.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `500` | `41` | Рассылка сейчас не отправляется |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#pause-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{campaign_id}/resume": { "post": { "operationId": "resume-campaign", "summary": "Возобновить отправку", "tags": [ "Рассылки" ], "description": "Продолжает рассылку, поставленную на паузу, с того места, где она остановилась.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `401` | `42` | Рассылки на паузе с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#resume-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{campaign_id}/resend": { "post": { "operationId": "resend-campaign", "summary": "Переотправить неоткрывшим", "tags": [ "Рассылки" ], "description": "Создаёт новую рассылку по тем получателям исходной, кто её не открыл. Обычный приём — повторить письмо через несколько дней с другой темой.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `new_subject` | string | Тема повторного письма. По умолчанию берётся исходная. |\n\n**Что возвращается**\n\nИдентификатор созданной рассылки.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Исходной рассылки нет |\n| `500` | `40` | Рассылка не в статусе `PROCESSING` или `SENT` |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#resend-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор исходной рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "campaign_id": 501255 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_subject": { "type": "string", "description": "Тема повторного письма. По умолчанию берётся исходная." } }, "additionalProperties": true }, "example": { "new_subject": "Вы не видели: скидки до 40%" } } } } } }, "/campaigns/{campaign_id}/attachments": { "get": { "operationId": "get-attachments", "summary": "Вложения рассылки", "tags": [ "Рассылки" ], "description": "Список файлов, приложенных к рассылке. Возвращается не больше десяти вложений.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n| `404` | `4` | Вложений нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#get-attachments)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 7712, "campaign_id": 501233, "name": "prays-list.pdf", "size": 184320, "link": "" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "add-attachment", "summary": "Приложить файл", "tags": [ "Рассылки" ], "description": "Скачивает файл по указанной ссылке и прикладывает его к письму. Суммарный размер вложений ограничен тарифом.\n\n> **Примечание.** С параметром `separate_link` файл не скачивается: в письмо вставляется ссылка на него. Так стоит поступать с крупными файлами — письмо останется лёгким.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `url` | string, обязательный | Ссылка на файл. |\n| `name` | string | Имя файла в письме. По умолчанию берётся из ссылки; кириллица транслитерируется. |\n| `separate_link` | флаг | Не прикладывать файл, а вставить ссылку на него. |\n\n**Что возвращается**\n\nИдентификатор вложения.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан `url` |\n| `500` | `33` | Недопустимый формат файла — `.php` и `.exe` запрещены |\n| `402` | `25` | Файл с таким именем уже приложен |\n| `413` | `26` | Превышен лимит на размер вложений |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#add-attachment)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 7712 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Ссылка на файл." }, "name": { "type": "string", "description": "Имя файла в письме. По умолчанию берётся из ссылки; кириллица транслитерируется." }, "separate_link": { "type": "string", "description": "Не прикладывать файл, а вставить ссылку на него. Признак: передайте 1." } }, "required": [ "url" ], "additionalProperties": true }, "example": { "url": "https://example.ru/files/prays-list.pdf", "name": "Прайс-лист.pdf" } } } } } }, "/campaigns/{campaign_id}/attachments/{id}": { "delete": { "operationId": "delete-attachment", "summary": "Удалить вложение", "tags": [ "Рассылки" ], "description": "Открепляет файл от рассылки и удаляет его с диска.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n| `404` | `27` | Вложение не найдено |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#delete-attachment)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "id", "in": "path", "required": true, "description": "Идентификатор вложения из [списка вложений](https://dashamail.ru/api/campaigns/#get-attachments).", "schema": { "type": "integer" }, "example": "7712" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/folders": { "get": { "operationId": "get-folders", "summary": "Папки рассылок", "tags": [ "Рассылки" ], "description": "Список папок, по которым разложены рассылки.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Папок нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#get-folders)", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Вернуть одну папку.", "schema": { "type": "integer" } }, { "name": "name", "in": "query", "required": false, "description": "Найти папку по точному названию.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 33, "name": "Дайджесты" }, { "id": 34, "name": "Акции" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/campaigns/{campaign_id}/move": { "post": { "operationId": "move-campaign", "summary": "Переместить рассылку в папку", "tags": [ "Рассылки" ], "description": "Перекладывает рассылку в указанную папку.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `folder_id` | integer, обязательный | Идентификатор папки из [списка папок](https://dashamail.ru/api/campaigns/#get-folders). |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n| `500` | `39` | Папки с таким `folder_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/campaigns/#move-campaign)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "folder_id": { "type": "integer", "description": "Идентификатор папки из [списка папок](https://dashamail.ru/api/campaigns/#get-folders)." } }, "required": [ "folder_id" ], "additionalProperties": true }, "example": { "folder_id": 34 } } } } } }, "/automations": { "get": { "operationId": "get-automations", "summary": "Список автоматизаций", "tags": [ "Автоматизации" ], "description": "Возвращает автоматизации аккаунта вместе с настройками события и задержки.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Автоматизаций нет |\n\n[Метод в документации](https://dashamail.ru/api/automations/#get-automations)", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Вернуть одну автоматизацию.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 502001, "name": "Welcome-письмо", "subject": "Добро пожаловать!", "from_name": "Ромашка", "from_email": "news@example.ru", "list_id": "128341", "status": "SUBSCRIBE", "action": "form,add", "auto_delay1": 0, "auto_delay2": 0 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-automation", "summary": "Создать автоматизацию", "tags": [ "Автоматизации" ], "description": "Создаёт триггерное письмо. Содержимое проверяется сразу — как при запуске обычной рассылки, включая наличие [ссылки отписки](https://dashamail.ru/api/campaigns/#unsub-link).\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `list_id` | integer | JSON-строка, обязательный | Адресная база, за которой следит автоматизация. Несколько баз — JSON-массив идентификаторов. |\n| `subject` | string, обязательный | Тема письма. |\n| `from_email` | string, обязательный | Адрес отправителя. |\n| `from_name` | string, обязательный | Имя отправителя. |\n| `event` | string, обязательный | Служебный параметр запроса — передайте сюда то же значение, что и в `action`. |\n| `action` | string | Событие запуска, см. [список событий](https://dashamail.ru/api/automations/#events). Несколько значений перечисляются через запятую. По умолчанию: `form`. |\n| `delay_1` | integer | Величина задержки перед отправкой. По умолчанию: `0`. |\n| `delay_2` | string | Единица измерения задержки. Допустимые значения: `hour`, `day`, `week`. По умолчанию: `0`. |\n| `campaigns` | string | Для событий `open`, `click` и `href` — идентификаторы рассылок, за которыми следить. |\n| `schedule_time` | string | Ограничение по времени суток для отправки. |\n| `auto` | флаг | Со значением `1` письмо проверяется как готовое к отправке: тема, отправитель, текст и ссылка отписки должны быть заполнены. |\n| `html` | string | HTML-версия письма. |\n| `plain_text` | string | Текстовая версия письма. |\n| `name` | string | Внутреннее название. |\n| `esegment` | JSON-строка | Условия сегментации базы. |\n| `track_opens` | string | Отслеживать открытия. Допустимые значения: `Y`, `N`. По умолчанию: `Y`. |\n| `track_clicks` | string | Отслеживать клики. Допустимые значения: `Y`, `N`. По умолчанию: `Y`. |\n| `analytics` | string | Добавлять UTM-метки. Допустимые значения: `Y`, `N`. По умолчанию: `N`. |\n\n**Что возвращается**\n\nИдентификатор созданной автоматизации.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не переданы обязательные параметры |\n| `401` | `2` | В комбинации событий использованы `open`, `click` или `edit` |\n| `500` | `14` | Не задана тема письма |\n| `500` | `17` | Нет ни HTML-, ни текстовой версии |\n| `500` | `18` | Нет ссылки отписки в HTML |\n| `404` | `5` | Указанной адресной базы не существует |\n\n[Метод в документации](https://dashamail.ru/api/automations/#create-automation)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "campaign_id": 502001 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "list_id": { "type": "string", "description": "Адресная база, за которой следит автоматизация. Несколько баз — JSON-массив идентификаторов." }, "subject": { "type": "string", "description": "Тема письма." }, "from_email": { "type": "string", "description": "Адрес отправителя." }, "from_name": { "type": "string", "description": "Имя отправителя." }, "event": { "type": "string", "description": "Служебный параметр запроса — передайте сюда то же значение, что и в `action`." }, "action": { "type": "string", "description": "Событие запуска, см. [список событий](https://dashamail.ru/api/automations/#events). Несколько значений перечисляются через запятую." }, "delay_1": { "type": "integer", "description": "Величина задержки перед отправкой." }, "delay_2": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Единица измерения задержки." }, "campaigns": { "type": "string", "description": "Для событий `open`, `click` и `href` — идентификаторы рассылок, за которыми следить." }, "schedule_time": { "type": "string", "description": "Ограничение по времени суток для отправки." }, "auto": { "type": "string", "description": "Со значением `1` письмо проверяется как готовое к отправке: тема, отправитель, текст и ссылка отписки должны быть заполнены. Признак: передайте 1." }, "html": { "type": "string", "description": "HTML-версия письма." }, "plain_text": { "type": "string", "description": "Текстовая версия письма." }, "name": { "type": "string", "description": "Внутреннее название." }, "esegment": { "type": "string", "description": "Условия сегментации базы." }, "track_opens": { "type": "string", "enum": [ "Y", "N" ], "description": "Отслеживать открытия." }, "track_clicks": { "type": "string", "enum": [ "Y", "N" ], "description": "Отслеживать клики." }, "analytics": { "type": "string", "enum": [ "Y", "N" ], "description": "Добавлять UTM-метки." } }, "required": [ "list_id", "subject", "from_email", "from_name", "event" ], "additionalProperties": true }, "example": { "list_id": 128341, "subject": "Добро пожаловать!", "from_email": "news@example.ru", "from_name": "Ромашка", "event": "form,add", "action": "form,add", "delay_1": 1, "delay_2": "hour", "html": "Спасибо за подписку
отписаться" } } } } } }, "/automations/{campaign_id}": { "put": { "operationId": "update-automation", "summary": "Изменить автоматизацию", "tags": [ "Автоматизации" ], "description": "Меняет содержимое письма, событие запуска или задержку. Незаданные параметры сохраняют прежние значения.\n\n> **Примечание.** После изменения содержимого автоматизация снова проходит модерацию.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `subject` | string | Тема письма. |\n| `from_email` | string | Адрес отправителя. |\n| `from_name` | string | Имя отправителя. |\n| `html` | string | HTML-версия письма. |\n| `plain_text` | string | Текстовая версия письма. |\n| `list_id` | integer | JSON-строка | Сменить адресную базу. |\n| `action` | string | Событие запуска. |\n| `delay_1` | integer | Величина задержки. |\n| `delay_2` | string | Единица измерения задержки. Допустимые значения: `hour`, `day`, `week`. |\n| `campaigns` | string | Отслеживаемые рассылки для событий по открытиям и кликам. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Автоматизации с таким `campaign_id` нет |\n| `500` | `20` | Указанная рассылка не является автоматизацией |\n\n[Метод в документации](https://dashamail.ru/api/automations/#update-automation)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор автоматизации.", "schema": { "type": "integer" }, "example": "502001" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Тема письма." }, "from_email": { "type": "string", "description": "Адрес отправителя." }, "from_name": { "type": "string", "description": "Имя отправителя." }, "html": { "type": "string", "description": "HTML-версия письма." }, "plain_text": { "type": "string", "description": "Текстовая версия письма." }, "list_id": { "type": "string", "description": "Сменить адресную базу." }, "action": { "type": "string", "description": "Событие запуска." }, "delay_1": { "type": "integer", "description": "Величина задержки." }, "delay_2": { "type": "string", "enum": [ "hour", "day", "week" ], "description": "Единица измерения задержки." }, "campaigns": { "type": "string", "description": "Отслеживаемые рассылки для событий по открытиям и кликам." } }, "additionalProperties": true }, "example": { "subject": "Добро пожаловать в Ромашку!", "delay_1": 2, "delay_2": "hour" } } } } }, "delete": { "operationId": "delete-automation", "summary": "Удалить автоматизацию", "tags": [ "Автоматизации" ], "description": "Останавливает и удаляет автоматизацию. Уже поставленные в очередь письма не отправляются.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Автоматизации с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/automations/#delete-automation)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор автоматизации.", "schema": { "type": "integer" }, "example": "502001" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/automations/{campaign_id}/trigger": { "post": { "operationId": "trigger-automation", "summary": "Запустить автоматизацию вручную", "tags": [ "Автоматизации" ], "description": "Отправляет письмо автоматизации конкретному подписчику, не дожидаясь события. Удобно для проверки вёрстки и для сценариев, где момент отправки решает ваша система.\n\n> **Примечание.** Предыдущая отправка этого письма тому же подписчику сбрасывается, поэтому повторный запуск сработает даже если письмо уже уходило.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `email` | string, обязательный | Адрес получателя. Подписчик должен существовать в аккаунте. |\n| `member_id` | integer | Идентификатор подписчика вместо адреса. |\n| `delay` | integer | Задержка в секундах. Без неё письмо уходит немедленно, с ней — планируется на указанное время. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Автоматизации с таким `campaign_id` нет |\n| `500` | `37` | Автоматизация ещё не прошла модерацию |\n| `404` | `9` | Подписчика с таким адресом нет |\n\n[Метод в документации](https://dashamail.ru/api/automations/#trigger-automation)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор автоматизации.", "schema": { "type": "integer" }, "example": "502001" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Адрес получателя. Подписчик должен существовать в аккаунте." }, "member_id": { "type": "integer", "description": "Идентификатор подписчика вместо адреса." }, "delay": { "type": "integer", "description": "Задержка в секундах. Без неё письмо уходит немедленно, с ней — планируется на указанное время." } }, "required": [ "email" ], "additionalProperties": true }, "example": { "email": "ivan@example.com" } } } } } }, "/automations/{campaign_id}/copy": { "post": { "operationId": "copy-automation", "summary": "Скопировать автоматизацию", "tags": [ "Автоматизации" ], "description": "Создаёт копию автоматизации со всеми настройками события и задержки.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `format` | string | Формат копирования. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Исходной автоматизации нет |\n\n[Метод в документации](https://dashamail.ru/api/automations/#copy-automation)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор исходной автоматизации.", "schema": { "type": "integer" }, "example": "502001" } ], "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "campaign_id": 502014 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "description": "Формат копирования." } }, "additionalProperties": true } } } } } }, "/templates": { "get": { "operationId": "get-templates", "summary": "HTML-шаблоны", "tags": [ "Шаблоны" ], "description": "Возвращает сохранённые HTML-шаблоны аккаунта вместе с вёрсткой, от новых к старым.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Шаблонов нет |\n\n[Метод в документации](https://dashamail.ru/api/templates/#get-templates)", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Вернуть один шаблон.", "schema": { "type": "integer" } }, { "name": "name", "in": "query", "required": false, "description": "Найти шаблон по точному названию.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 4412, "name": "Базовый одноколоночный", "html": "…" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-template", "summary": "Сохранить шаблон", "tags": [ "Шаблоны" ], "description": "Сохраняет вёрстку как HTML-шаблон.\n\nВ `template` можно передать либо саму вёрстку, либо **число** — идентификатор рассылки, чью вёрстку нужно сохранить.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `name` | string, обязательный | Название шаблона. |\n| `template` | string, обязательный | HTML-вёрстка либо `campaign_id` числом. |\n| `body` | string, обязательный | Служебный параметр запроса — продублируйте сюда значение `template`. |\n| `campaign_id` | integer | Рассылка-источник вёрстки. Указывается вместе с числовым `template`. |\n| `cloud` | флаг | Выгрузить изображения из вёрстки в облачное хранилище DashaMail. |\n\n**Что возвращается**\n\nИдентификатор созданного шаблона.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан `name` или `template` |\n| `404` | `22` | Рассылки-источника с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/templates/#create-template)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 4412 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Название шаблона." }, "template": { "type": "string", "description": "HTML-вёрстка либо `campaign_id` числом." }, "body": { "type": "string", "description": "Служебный параметр запроса — продублируйте сюда значение `template`." }, "campaign_id": { "type": "integer", "description": "Рассылка-источник вёрстки. Указывается вместе с числовым `template`." }, "cloud": { "type": "string", "description": "Выгрузить изображения из вёрстки в облачное хранилище DashaMail. Признак: передайте 1." } }, "required": [ "name", "template", "body" ], "additionalProperties": true }, "example": { "name": "Базовый одноколоночный", "template": "Заголовок
", "body": "Заголовок
" } } } } } }, "/templates/saved": { "get": { "operationId": "get-saved-templates", "summary": "Сохранённые рассылки", "tags": [ "Шаблоны" ], "description": "Возвращает рассылки в статусе `TEMPLATE` — без вёрстки, только идентификатор, название и папку. Чтобы получить HTML, запросите рассылку через [её эндпоинт](https://dashamail.ru/api/campaigns/#get-campaign).\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Сохранённых рассылок нет |\n\n[Метод в документации](https://dashamail.ru/api/templates/#get-saved-templates)", "parameters": [ { "name": "id", "in": "query", "required": false, "description": "Вернуть одну запись.", "schema": { "type": "integer" } }, { "name": "name", "in": "query", "required": false, "description": "Найти по точному названию.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 501100, "name": "Шаблон дайджеста", "folder_id": 33 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/templates/{id}": { "delete": { "operationId": "delete-template", "summary": "Удалить шаблон", "tags": [ "Шаблоны" ], "description": "Удаляет HTML-шаблон. Рассылки, созданные на его основе, не затрагиваются — вёрстка в них уже своя.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `500` | `28` | Шаблона с таким идентификатором нет |\n\n[Метод в документации](https://dashamail.ru/api/templates/#delete-template)", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Идентификатор шаблона.", "schema": { "type": "integer" }, "example": "4412" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/summary": { "get": { "operationId": "report-summary", "summary": "Сводка по рассылке", "tags": [ "Отчёты" ], "description": "Главные показатели рассылки одним объектом. Отсюда стоит начинать: остальные отчёты нужны, когда требуется детализация.\n\n> **Примечание.** Параметр `fast` отдаёт заранее посчитанные значения — это заметно быстрее, но несовместимо с фильтром по времени.\n\n**Что возвращается**\n\n`opened` и `clicked` — общее число событий, `unique_opened` и `unique_clicked` — число уникальных подписчиков. Возвраты разложены по типам: `hard` — несуществующие адреса, `soft` — временные отказы, `spam` и `spam_blocked` — отклонения антиспам-фильтрами, `blk` — прочие блокировки.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-summary)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "fast", "in": "query", "required": false, "description": "Взять готовые агрегаты вместо пересчёта. Игнорируется, если задан период. Признак: передайте 1.", "schema": { "type": "string" }, "example": 1 }, { "name": "time_start", "in": "query", "required": false, "description": "Начало периода. При заданном периоде поле `sent` из ответа исключается.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "time_end", "in": "query", "required": false, "description": "Конец периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "detailed", "in": "query", "required": false, "description": "Со значением `1` сводка разбивается по рассылкам.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "sent": 1284, "opened": 741, "unique_opened": 512, "clicked": 168, "unique_clicked": 121, "unsubscribed": 6, "complained": 1, "hard": 12, "soft": 4, "spam": 0, "spam_blocked": 3, "blk": 1, "preview": 22, "total_events": 2258, "first_sent": "2026-04-05 10:00:04", "first_open": "2026-04-05 10:01:37", "last_open": "2026-04-08 21:14:52", "first_click": "2026-04-05 10:02:11", "last_click": "2026-04-08 19:02:40" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/{metric}": { "get": { "operationId": "report-lists", "summary": "Списки получателей по событию", "tags": [ "Отчёты" ], "description": "Возвращает подписчиков, с которыми произошло указанное событие. Один и тот же формат для семи метрик: `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `unsubscribed`.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан ни `campaign_id`, ни `external_campaign_id` |\n| `404` | `22` | Рассылки с таким идентификатором нет |\n| `500` | `23` | Недопустимое поле в `order` |\n| `404` | `4` | Событий такого типа не было |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-lists)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "metric", "in": "path", "required": true, "description": "Событие.", "schema": { "type": "string", "enum": [ "sent", "delivered", "opened", "clicked", "bounced", "complained", "unsubscribed" ] }, "example": "opened" }, { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" }, "example": 2 }, { "name": "order", "in": "query", "required": false, "description": "Сортировка, см. [список полей](https://dashamail.ru/api/reports/#sorting).", "schema": { "type": "string" } }, { "name": "external_campaign_id", "in": "query", "required": false, "description": "Использовать ваш внешний идентификатор рассылки вместо `campaign_id`.", "schema": { "type": "string" } }, { "name": "old_reports", "in": "query", "required": false, "description": "Читать из архивного хранилища вместо аналитической базы. Нужен для очень старых рассылок. Признак: передайте 1.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "member_id": 90412881, "campaign_id": 501233, "list_id": 128341, "email": "ivan@example.com", "sent_time": "2026-04-05 10:00:12" }, { "member_id": 90412882, "campaign_id": 501233, "list_id": 128341, "email": "maria@example.com", "sent_time": "2026-04-05 10:00:13" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/events": { "get": { "operationId": "report-events", "summary": "Лента событий", "tags": [ "Отчёты" ], "description": "Все события рассылки в одном потоке, с фильтрами по времени, типу и подписчику. Подходит для синхронизации событий с вашей аналитикой.\n\n> **Примечание.** По умолчанию берутся события за сегодня. Чтобы получить события за другой период, задайте `time_start` и `time_end` явно.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n| `404` | `4` | За период событий нет |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-events)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "time_start", "in": "query", "required": false, "description": "Начало периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" }, "example": "2026-04-05 00:00:00" }, { "name": "time_end", "in": "query", "required": false, "description": "Конец периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "event_type", "in": "query", "required": false, "description": "Оставить события одного типа.", "schema": { "type": "string", "enum": [ "SENT", "OPENED", "CLICKED", "PREVIEW", "UNSUBSCRIBED", "COMPLAINED", "BOUNCED" ] }, "example": "CLICKED" }, { "name": "email", "in": "query", "required": false, "description": "События одного подписчика.", "schema": { "type": "string" } }, { "name": "merge", "in": "query", "required": false, "description": "Дополнительные поля подписчика, которые нужно приложить к каждому событию — например `[\"merge_1\",\"merge_2\"]`.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" }, "example": 2 }, { "name": "order", "in": "query", "required": false, "description": "Сортировка.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "event_time": "2026-04-05 10:02:11", "event_type": "CLICKED", "email": "ivan@example.com", "url_original": "https://example.ru/sale", "device": "PC", "browser": "Chrome" }, { "event_time": "2026-04-05 10:04:55", "event_type": "CLICKED", "email": "maria@example.com", "url_original": "https://example.ru/sale", "device": "Mobile", "browser": "Safari" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/clickstat": { "get": { "operationId": "report-clickstat", "summary": "Клики по ссылкам", "tags": [ "Отчёты" ], "description": "Сколько раз кликнули по каждой ссылке письма, от популярных к редким.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `22` | Рассылки с таким `campaign_id` нет |\n| `404` | `4` | Кликов не было |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-clickstat)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "url": "https://example.ru/sale", "clicks": 121 }, { "url": "https://example.ru/catalog", "clicks": 47 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/userclicks": { "get": { "operationId": "report-userclicks", "summary": "Кто кликнул по ссылке", "tags": [ "Отчёты" ], "description": "Подписчики, кликнувшие по указанной ссылке, со временем клика. Выборка ограничена последним годом.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан `url` |\n| `404` | `4` | Кликов по этой ссылке не было |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-userclicks)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "url", "in": "query", "required": true, "description": "Ссылка целиком, в точности как в [отчёте по кликам](https://dashamail.ru/api/reports/#report-clickstat).", "schema": { "type": "string" }, "example": "https://example.ru/sale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "url": "https://example.ru/sale", "email": "ivan@example.com", "click_time": "2026-04-05 10:02:11" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/bouncestat": { "get": { "operationId": "report-bouncestat", "summary": "Возвраты по кодам", "tags": [ "Отчёты" ], "description": "Группировка возвратов по SMTP-кодам с расшифровкой. Помогает понять, дело в несуществующих адресах или в репутации отправителя.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Возвратов не было |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-bouncestat)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "bounce_code": "5.1.1", "count": 9, "description": "Bad destination mailbox address" }, { "bounce_code": "5.2.2", "count": 3, "description": "Mailbox full" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/domains": { "get": { "operationId": "report-domains", "summary": "Показатели по доменам", "tags": [ "Отчёты" ], "description": "Доставляемость и вовлечённость в разрезе почтовых провайдеров. Проседание по одному домену обычно означает проблему с репутацией именно у него.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Данных за период нет |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-domains)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "time_start", "in": "query", "required": false, "description": "Начало периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "time_end", "in": "query", "required": false, "description": "Конец периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" } }, { "name": "order_field", "in": "query", "required": false, "description": "Поле сортировки.", "schema": { "type": "string" } }, { "name": "order_type", "in": "query", "required": false, "description": "Направление сортировки.", "schema": { "type": "string", "enum": [ "asc", "desc" ] }, "example": "asc" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "domain": "mail.ru", "sent": 612, "opened": 380, "unique_opened": 254, "clicked": 71, "unique_clicked": 55, "complained": 1, "unsubsribed": 3 }, { "domain": "yandex.ru", "sent": 431, "opened": 268, "unique_opened": 190, "clicked": 63, "unique_clicked": 47, "complained": 0, "unsubsribed": 2 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/geo": { "get": { "operationId": "report-geo", "summary": "География открытий", "tags": [ "Отчёты" ], "description": "Распределение событий по регионам. Ключ — код региона, значение — количество событий.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Данных нет |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-geo)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "77": 412, "78": 133, "16": 51 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/clients": { "get": { "operationId": "report-clients", "summary": "Почтовые клиенты и устройства", "tags": [ "Отчёты" ], "description": "Чем получатели читают письмо: браузеры, десктопные клиенты, мобильные устройства. Полезно перед изменением вёрстки.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Открытий и кликов не было |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-clients)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "chrome": 210, "safari": 122, "firefox": 44, "yandexbrowser": 88, "opera": 12, "ie": 3, "other": 19, "browsers": 498 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/reports/{campaign_id}/codes": { "get": { "operationId": "report-codes", "summary": "Коды подтверждения", "tags": [ "Отчёты" ], "description": "Одноразовые коды, разосланные в рамках рассылки, с адресами получателей и временем выдачи.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Кодов нет |\n\n[Метод в документации](https://dashamail.ru/api/reports/#report-codes)", "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "description": "Идентификатор рассылки.", "schema": { "type": "integer" }, "example": "501233" }, { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" } }, { "name": "order", "in": "query", "required": false, "description": "Сортировка.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "email": "ivan@example.com", "code": "481920", "date": "2026-04-05 10:00:12" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactional/messages": { "post": { "operationId": "send-message", "summary": "Отправить письмо", "tags": [ "Транзакционные письма" ], "description": "Ставит письмо в очередь отправки и сразу возвращает его идентификатор. Фактическая доставка происходит асинхронно — следите за ней через [проверку статуса](https://dashamail.ru/api/transactional/#check-message) или webhooks.\n\nНужны как минимум три вещи: получатель, отправитель (`from_email` либо заголовок `From` внутри `headers`) и текст письма (`message` либо `plain_text`).\n\n> **Примечание.** В `to` можно перечислить несколько адресов через запятую. Тогда каждому уйдёт отдельное письмо, а в `message_id` можно передать столько же идентификаторов, тоже через запятую.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `to` | string, обязательный | Адрес получателя. Допустима форма `Иван ПетровСпасибо за заказ! Мы уже собираем его.
", "plain_text": "Спасибо за заказ! Мы уже собираем его.", "message_id": "order-1024-paid" } } } } } }, "/transactional/messages/{transaction_id}": { "get": { "operationId": "check-message", "summary": "Статус письма", "tags": [ "Транзакционные письма" ], "description": "Возвращает текущий статус письма и historию его событий. Данные появляются через несколько секунд после отправки.\n\n> **Примечание.** Поиск по конкретному письму доступен за последние шесть месяцев. За более старыми данными обращайтесь к [журналу](https://dashamail.ru/api/transactional/#get-log).\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `transaction_id` | string, обязательный | Идентификатор письма — продублируйте значение из пути в строке запроса. |\n\n**Что возвращается**\n\n`data` — последнее состояние письма, `log` — последовательность событий. Даты событий лежат в полях `datesent`, `dateopened`, `dateclicked`, `datebounced` и подобных.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан `transaction_id` |\n| `500` | `34` | В аккаунте не настроен домен отправки |\n| `402` | `35` | Функция недоступна на текущем тарифе |\n| `404` | `4` | Письма с таким идентификатором не найдено |\n\n[Метод в документации](https://dashamail.ru/api/transactional/#check-message)", "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Идентификатор письма из ответа на отправку.", "schema": { "type": "string" }, "example": "order-1024-paid" }, { "name": "transaction_id", "in": "query", "required": false, "description": "", "schema": { "type": "string" }, "example": "order-1024-paid" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "data": { "to": "ivan@example.com", "status": 3, "statusname": "Delivered", "date": "2026-04-12T10:15:03Z", "datesent": "2026-04-12T10:15:01Z", "delivery_info": "Доставлено: 10:15:03 250 2.0.0 OK", "statuschangedate": "2026-04-12T10:15:03Z" } } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "Идентификатор письма — продублируйте значение из пути в строке запроса." } }, "required": [ "transaction_id" ], "additionalProperties": true } } } } } }, "/transactional/log": { "get": { "operationId": "get-log", "summary": "Журнал отправок", "tags": [ "Транзакционные письма" ], "description": "События транзакционных писем аккаунта с фильтрами. Основной инструмент для разбора инцидентов: «почему клиент не получил письмо».\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `500` | `34` | В аккаунте не настроен домен отправки |\n| `402` | `35` | Функция недоступна на текущем тарифе |\n| `404` | `4` | Событий по фильтру нет |\n\n[Метод в документации](https://dashamail.ru/api/transactional/#get-log)", "parameters": [ { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" }, "example": 2 }, { "name": "sort", "in": "query", "required": false, "description": "Направление сортировки по времени события.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] }, "example": "ASC" }, { "name": "message_id", "in": "query", "required": false, "description": "События одного письма.", "schema": { "type": "string" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "События одной кампании.", "schema": { "type": "string" } }, { "name": "event_type", "in": "query", "required": false, "description": "Типы событий через запятую либо `all`.", "schema": { "type": "string", "enum": [ "SENT", "DELIVERED", "OPENED", "CLICKED", "BOUNCED", "COMPLAINED", "UNSUBSCRIBED", "all" ] }, "example": "BOUNCED" }, { "name": "emails", "in": "query", "required": false, "description": "Адреса получателей через запятую.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "Начало периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "to", "in": "query", "required": false, "description": "Конец периода.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "url", "in": "query", "required": false, "description": "Фильтр по ссылке для событий клика.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "event_time": "2026-04-12 10:15:40", "event_type": "BOUNCED", "email": "nobody@example.com", "message_id": "order-1025-paid", "bounce_code": "5.1.1", "bounce_reason": "Bad destination mailbox address" }, { "event_time": "2026-04-12 09:02:11", "event_type": "BOUNCED", "email": "old@example.com", "message_id": "order-1019-paid", "bounce_code": "5.2.2", "bounce_reason": "Mailbox full" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/transactional/stats": { "get": { "operationId": "get-stats", "summary": "Статистика отправок", "tags": [ "Транзакционные письма" ], "description": "Агрегированные показатели транзакционных писем за период, разложенные по временным интервалам. Годится для построения графиков доставляемости.\n\n> **Примечание.** Ширина интервала подбирается по периоду автоматически: пять минут для `1h`, час для `24h`, сутки для `7d` и `30d`.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `402` | `35` | Функция недоступна на текущем тарифе |\n| `404` | `4` | Данных за период нет |\n\n[Метод в документации](https://dashamail.ru/api/transactional/#get-stats)", "parameters": [ { "name": "period", "in": "query", "required": false, "description": "Период отчёта. Значение `custom` включает `start_date` и `finish_date`.", "schema": { "type": "string", "enum": [ "1h", "24h", "7d", "30d", "custom" ] }, "example": "24h" }, { "name": "start_date", "in": "query", "required": false, "description": "Начало периода при `period=custom`.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "finish_date", "in": "query", "required": false, "description": "Конец периода при `period=custom`.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "groupby", "in": "query", "required": false, "description": "Шаг группировки при `period=custom`.", "schema": { "type": "string", "enum": [ "hour", "day", "week", "month" ] }, "example": "hour" }, { "name": "campaign_id", "in": "query", "required": false, "description": "Только письма указанной кампании.", "schema": { "type": "string" } }, { "name": "domain", "in": "query", "required": false, "description": "Только письма с указанного домена отправки.", "schema": { "type": "string" } }, { "name": "start", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "time": "2026-04-12 09:00", "sent": 412, "delivered": 401, "opened": 188, "clicked": 42, "bounced": 9, "complained": 0 }, { "time": "2026-04-12 10:00", "sent": 388, "delivered": 380, "opened": 165, "clicked": 37, "bounced": 6, "complained": 1 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/balance": { "get": { "operationId": "get-balance", "summary": "Баланс и лимиты", "tags": [ "Аккаунт" ], "description": "Текущие лимиты аккаунта и число активных подписчиков. Самый дешёвый запрос — годится для проверки работоспособности ключа.\n\n**Что возвращается**\n\nНа поштучных тарифах `limit_emails` — остаток оплаченных писем, а `limit_members` равен нулю. На месячных тарифах возвращается и `expiration_date` — дата окончания оплаченного периода.\n\n[Метод в документации](https://dashamail.ru/api/account/#get-balance)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "limit_members": 5000, "limit_emails": 50000, "expiration_date": "01.10.2026 12:00:00", "members": 1284 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/senders": { "get": { "operationId": "get-senders", "summary": "Подтверждённые отправители", "tags": [ "Аккаунт" ], "description": "Список адресов, подтверждённых как обратные. Возвращается массивом строк, не более ста записей.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Подтверждённых адресов нет |\n\n[Метод в документации](https://dashamail.ru/api/account/#get-senders)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ "news@example.ru", "support@example.ru" ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/senders/confirm": { "post": { "operationId": "confirm-sender", "summary": "Отправить письмо подтверждения", "tags": [ "Аккаунт" ], "description": "Отправляет на указанный адрес письмо со ссылкой подтверждения. Адрес станет доступен как обратный после того, как получатель перейдёт по ссылке.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `email` | string, обязательный | Адрес, который нужно подтвердить. |\n| `code` | string, обязательный | Служебный параметр запроса — передайте сюда тот же адрес. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не переданы обязательные параметры |\n| `500` | `49` | Адрес уже подтверждён |\n| `500` | `50` | Одноразовый почтовый адрес |\n| `500` | `51` | Публичный домен Mail.ru запрещён политикой DMARC |\n| `500` | `48` | Не удалось отправить письмо подтверждения |\n\n[Метод в документации](https://dashamail.ru/api/account/#confirm-sender)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Адрес, который нужно подтвердить." }, "code": { "type": "string", "description": "Служебный параметр запроса — передайте сюда тот же адрес." } }, "required": [ "email", "code" ], "additionalProperties": true }, "example": { "email": "news@example.ru", "code": "news@example.ru" } } } } } }, "/account/domains": { "get": { "operationId": "get-domains", "summary": "Домены отправки", "tags": [ "Аккаунт" ], "description": "Домены аккаунта и состояние их DNS-настроек. Значения берутся из последней проверки — чтобы обновить их, вызовите [проверку DNS](https://dashamail.ru/api/account/#check-domains).\n\n**Что возвращается**\n\n`type` различает домен отправки (`domain`) и домен статистики (`stat_domain`). `valid` — домен полностью настроен; `valid_spf` и `valid_dkim` показывают состояние отдельных записей; `double_spf` сигнализирует о двух SPF-записях на домене — это ошибка конфигурации.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Доменов нет |\n\n[Метод в документации](https://dashamail.ru/api/account/#get-domains)", "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "Вернуть только этот домен отправки.", "schema": { "type": "string" } }, { "name": "stat_domain", "in": "query", "required": false, "description": "Вернуть только этот домен статистики.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "domain": "example.ru", "type": "domain", "valid": 1, "valid_spf": 1, "valid_dkim": 1, "double_spf": 0, "last_update": "2026-04-10 03:00:00" }, { "domain": "stat.example.ru", "type": "stat_domain", "valid": 1, "last_update": "2026-04-10 03:00:00" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "add-domain", "summary": "Добавить домен", "tags": [ "Аккаунт" ], "description": "Регистрирует домен в аккаунте и возвращает DNS-записи, которые нужно прописать у регистратора. До того как записи появятся в DNS и пройдут [проверку](https://dashamail.ru/api/account/#check-domains), отправка с этого домена не заработает.\n\n> **Примечание.** Кроме домена отправки можно добавить домен статистики — тогда ссылки отслеживания в письмах будут вести на ваш поддомен, а не на домен DashaMail. Оба параметра можно передать в одном запросе.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `domain` | string, обязательный | Домен отправки. Национальные (кириллические) домены не поддерживаются. |\n| `stat_domain` | string | Поддомен для ссылок статистики, например `stat.example.ru`. |\n\n**Что возвращается**\n\nМассив DNS-записей: тип, имя и значение каждой. Имя DKIM-записи берите из ответа, а не из примера: у доменов, добавленных раньше, селектор `dm`, у новых — `dm2`.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `500` | `54` | Некорректный домен или национальное имя |\n| `500` | `56` | Домен уже добавлен либо занят другим аккаунтом |\n\n[Метод в документации](https://dashamail.ru/api/account/#add-domain)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "record_type": "TXT", "name": "example.ru.", "value": "v=spf1 include:_spf.dashasender.ru ~all", "valid": 0 }, { "record_type": "TXT", "name": "dm2._domainkey.example.ru.", "value": "v=DKIM1;p=MIIBIjANBgkq…;t=s", "valid": 0 }, { "record_type": "CNAME", "name": "stat.example.ru.", "value": "stat.dashamail.com.", "valid": 0 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Домен отправки. Национальные (кириллические) домены не поддерживаются." }, "stat_domain": { "type": "string", "description": "Поддомен для ссылок статистики, например `stat.example.ru`." } }, "required": [ "domain" ], "additionalProperties": true }, "example": { "domain": "example.ru", "stat_domain": "stat.example.ru" } } } } } }, "/account/domains/check": { "get": { "operationId": "check-domains", "summary": "Проверить DNS доменов", "tags": [ "Аккаунт" ], "description": "Запрашивает DNS и обновляет состояние доменов. Вызывайте после того, как прописали записи у регистратора — распространение изменений обычно занимает от нескольких минут до нескольких часов.\n\n**Что возвращается**\n\nТе же DNS-записи, что и при добавлении домена, но с актуальным полем `valid` у каждой. Пока хотя бы одна запись имеет `valid: 0`, домен настроен не полностью.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Доменов для проверки нет |\n| `500` | `57` | Домена статистики с таким именем нет |\n\n[Метод в документации](https://dashamail.ru/api/account/#check-domains)", "parameters": [ { "name": "domain", "in": "query", "required": false, "description": "Проверить только этот домен отправки.", "schema": { "type": "string" } }, { "name": "stat_domain", "in": "query", "required": false, "description": "Проверить только этот домен статистики.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "record_type": "TXT", "name": "example.ru.", "value": "v=spf1 include:_spf.dashasender.ru ~all", "valid": 1 }, { "record_type": "TXT", "name": "dm2._domainkey.example.ru.", "value": "v=DKIM1;p=MIIBIjANBgkq…;t=s", "valid": 1 } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/domains/{domain}": { "delete": { "operationId": "delete-domain", "summary": "Удалить домен", "tags": [ "Аккаунт" ], "description": "Убирает домен из аккаунта. После удаления отправка с адресов на этом домене прекращается.\n\n> **Примечание.** Служебные домены DashaMail удалить нельзя.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `delete_stat_domain` | string | Удалить заодно и домен статистики. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `500` | `54` | Домен нельзя удалить |\n\n[Метод в документации](https://dashamail.ru/api/account/#delete-domain)", "parameters": [ { "name": "domain", "in": "path", "required": true, "description": "Имя домена.", "schema": { "type": "string" }, "example": "example.ru" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "delete_stat_domain": { "type": "string", "description": "Удалить заодно и домен статистики." } }, "additionalProperties": true } } } } } }, "/account/webhooks": { "get": { "operationId": "get-webhooks", "summary": "Webhooks массовых рассылок", "tags": [ "Аккаунт" ], "description": "Текущие адреса, на которые уходят события массовых рассылок — объект вида «событие → URL».\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Webhooks не заданы или указанное событие не настроено |\n| `500` | `53` | Недопустимое значение `event_name` |\n\n[Метод в документации](https://dashamail.ru/api/account/#get-webhooks)", "parameters": [ { "name": "event_name", "in": "query", "required": false, "description": "Вернуть настройку только одного события.", "schema": { "type": "string", "enum": [ "open", "click", "hard", "spam", "unsub", "subscribe", "confirm" ] }, "example": "open" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "open": "https://example.ru/hooks/open", "click": "https://example.ru/hooks/click", "hard": "", "spam": "", "unsub": "https://example.ru/hooks/unsub", "subscribe": "", "confirm": "" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "add-webhooks", "summary": "Настроить webhooks массовых рассылок", "tags": [ "Аккаунт" ], "description": "Задаёт адреса приёма событий. Ключ каждого параметра — имя события, значение — URL. Передавайте только те события, которые нужно изменить; пустая строка отключает событие.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `open` | string | URL для событий открытия. |\n| `click` | string | URL для событий клика. |\n| `hard` | string | URL для невозвратных ошибок доставки. |\n| `spam` | string | URL для жалоб на спам. |\n| `unsub` | string | URL для отписок. |\n| `subscribe` | string | URL для новых подписок. |\n| `confirm` | string | URL для подтверждений подписки. |\n| `url` | string, обязательный | Служебный параметр запроса — продублируйте сюда любой из указанных выше адресов. |\n| `event` | string, обязательный | Служебный параметр запроса — имя настраиваемого события. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не переданы обязательные параметры |\n\n[Метод в документации](https://dashamail.ru/api/account/#add-webhooks)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "open": { "type": "string", "description": "URL для событий открытия." }, "click": { "type": "string", "description": "URL для событий клика." }, "hard": { "type": "string", "description": "URL для невозвратных ошибок доставки." }, "spam": { "type": "string", "description": "URL для жалоб на спам." }, "unsub": { "type": "string", "description": "URL для отписок." }, "subscribe": { "type": "string", "description": "URL для новых подписок." }, "confirm": { "type": "string", "description": "URL для подтверждений подписки." }, "url": { "type": "string", "description": "Служебный параметр запроса — продублируйте сюда любой из указанных выше адресов." }, "event": { "type": "string", "description": "Служебный параметр запроса — имя настраиваемого события." } }, "required": [ "url", "event" ], "additionalProperties": true }, "example": { "open": "https://example.ru/hooks/open", "click": "https://example.ru/hooks/click", "url": "https://example.ru/hooks/open", "event": "open" } } } } } }, "/account/webhooks/{event_name}": { "delete": { "operationId": "delete-webhook", "summary": "Удалить webhook", "tags": [ "Аккаунт" ], "description": "Отключает приём событий указанного типа.\n\n> **Внимание.** Если `event_name` не распознан, удаляются настройки **всех** событий сразу. Проверяйте имя события перед вызовом.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Webhooks не заданы или событие не настроено |\n| `500` | `53` | Недопустимое имя события |\n\n[Метод в документации](https://dashamail.ru/api/account/#delete-webhook)", "parameters": [ { "name": "event_name", "in": "path", "required": true, "description": "Имя события.", "schema": { "type": "string", "enum": [ "open", "click", "hard", "spam", "unsub", "subscribe", "confirm" ] }, "example": "click" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/account/webhooks/transactional": { "get": { "operationId": "get-tr-webhooks", "summary": "Webhooks транзакционных писем", "tags": [ "Аккаунт" ], "description": "Адреса приёма событий транзакционных писем. Набор событий отличается от массовых рассылок — здесь есть `send`, `delivered` и `dropped`.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Webhooks не заданы |\n| `500` | `53` | Недопустимое значение `event_name` |\n\n[Метод в документации](https://dashamail.ru/api/account/#get-tr-webhooks)", "parameters": [ { "name": "event_name", "in": "query", "required": false, "description": "Вернуть настройку одного события.", "schema": { "type": "string", "enum": [ "dropped", "open", "click", "hard", "spam", "unsub", "delivered", "send" ] }, "example": "dropped" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "send": "https://example.ru/hooks/tr-send", "delivered": "https://example.ru/hooks/tr-delivered", "dropped": "", "open": "", "click": "", "hard": "https://example.ru/hooks/tr-hard", "spam": "", "unsub": "" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "add-tr-webhooks", "summary": "Настроить webhooks транзакционных писем", "tags": [ "Аккаунт" ], "description": "Задаёт адреса приёма событий транзакционных писем. Формат тот же, что и для массовых рассылок: ключ — имя события, значение — URL.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `send` | string | URL для событий отправки. |\n| `delivered` | string | URL для событий доставки. |\n| `dropped` | string | URL для отброшенных писем. |\n| `open` | string | URL для открытий. |\n| `click` | string | URL для кликов. |\n| `hard` | string | URL для невозвратных ошибок. |\n| `spam` | string | URL для жалоб на спам. |\n| `unsub` | string | URL для отписок. |\n| `url` | string, обязательный | Служебный параметр запроса — продублируйте сюда любой из указанных выше адресов. |\n| `event` | string, обязательный | Служебный параметр запроса — имя настраиваемого события. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не переданы обязательные параметры |\n| `500` | `53` | Сначала нужно задать домен отправки |\n\n[Метод в документации](https://dashamail.ru/api/account/#add-tr-webhooks)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "send": { "type": "string", "description": "URL для событий отправки." }, "delivered": { "type": "string", "description": "URL для событий доставки." }, "dropped": { "type": "string", "description": "URL для отброшенных писем." }, "open": { "type": "string", "description": "URL для открытий." }, "click": { "type": "string", "description": "URL для кликов." }, "hard": { "type": "string", "description": "URL для невозвратных ошибок." }, "spam": { "type": "string", "description": "URL для жалоб на спам." }, "unsub": { "type": "string", "description": "URL для отписок." }, "url": { "type": "string", "description": "Служебный параметр запроса — продублируйте сюда любой из указанных выше адресов." }, "event": { "type": "string", "description": "Служебный параметр запроса — имя настраиваемого события." } }, "required": [ "url", "event" ], "additionalProperties": true }, "example": { "delivered": "https://example.ru/hooks/tr-delivered", "hard": "https://example.ru/hooks/tr-hard", "url": "https://example.ru/hooks/tr-delivered", "event": "delivered" } } } } } }, "/account/webhooks/transactional/{event_name}": { "delete": { "operationId": "delete-tr-webhook", "summary": "Удалить webhook транзакционных писем", "tags": [ "Аккаунт" ], "description": "Отключает приём событий указанного типа для транзакционных писем.\n\n> **Внимание.** Как и для массовых рассылок: нераспознанное имя события приводит к удалению настроек всех событий.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Webhooks не заданы или событие не настроено |\n| `500` | `53` | Недопустимое имя события |\n\n[Метод в документации](https://dashamail.ru/api/account/#delete-tr-webhook)", "parameters": [ { "name": "event_name", "in": "path", "required": true, "description": "Имя события.", "schema": { "type": "string", "enum": [ "dropped", "open", "click", "hard", "spam", "unsub", "delivered", "send" ] }, "example": "open" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/domains": { "get": { "operationId": "list-domains", "summary": "Домены приёма", "tags": [ "Обработка входящих" ], "description": "Список доменов, на которые аккаунт принимает почту.\n\n> **Примечание.** При первом обращении служебный поддомен аккаунта создаётся автоматически — отдельный запрос для этого не нужен.\n\n[Метод в документации](https://dashamail.ru/api/router/#list-domains)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 41, "domain": "u128341.in.dashamail.com", "is_default": true, "verified": 1, "created_at": "2026-04-01 12:00:00" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-domain", "summary": "Подключить свой домен", "tags": [ "Обработка входящих" ], "description": "Добавляет ваш поддомен для приёма писем. После добавления пропишите MX-запись из [инструкции](https://dashamail.ru/api/router/#mx-instructions) и запустите [проверку](https://dashamail.ru/api/router/#verify-domain).\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `domain` | string, обязательный | Поддомен для приёма почты, например `mail.example.ru`. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Домен не задан или некорректен |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#create-domain)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 42, "domain": "mail.example.ru", "verified": 0 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Поддомен для приёма почты, например `mail.example.ru`." } }, "required": [ "domain" ], "additionalProperties": true }, "example": { "domain": "mail.example.ru" } } } } } }, "/router/domains/{domain_id}/verify": { "post": { "operationId": "verify-domain", "summary": "Проверить MX-запись", "tags": [ "Обработка входящих" ], "description": "Проверяет, что MX-запись домена указывает на серверы DashaMail. До успешной проверки письма на этот домен не принимаются.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Домена с таким идентификатором нет |\n| `422` | `3` | MX-запись не найдена или указывает не на DashaMail |\n\n[Метод в документации](https://dashamail.ru/api/router/#verify-domain)", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Идентификатор домена.", "schema": { "type": "integer" }, "example": "42" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 42, "domain": "mail.example.ru", "verified": 1 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/domains/{domain_id}": { "delete": { "operationId": "delete-domain-router", "summary": "Удалить домен приёма", "tags": [ "Обработка входящих" ], "description": "Отключает приём почты на домен. Служебный домен аккаунта удалить нельзя.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Домена с таким идентификатором нет |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#delete-domain-router)", "parameters": [ { "name": "domain_id", "in": "path", "required": true, "description": "Идентификатор домена.", "schema": { "type": "integer" }, "example": "42" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/domains/mx": { "get": { "operationId": "mx-instructions", "summary": "Что прописать в DNS", "tags": [ "Обработка входящих" ], "description": "Возвращает MX-запись, которую нужно добавить у регистратора, чтобы почта на ваш домен приходила в DashaMail.\n\n[Метод в документации](https://dashamail.ru/api/router/#mx-instructions)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "mx_target": "in.dashamail.com", "priority": 10, "example": "mail.example.ru. IN MX 10 in.dashamail.com." } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/routes": { "get": { "operationId": "list-routes", "summary": "Список маршрутов", "tags": [ "Обработка входящих" ], "description": "Все маршруты аккаунта в порядке применения — по возрастанию `priority`.\n\n**Что возвращается**\n\n`match_count` и `last_matched_at` показывают, срабатывал ли маршрут — полезно при отладке условий. Поле `expression` — текстовая запись того же условия, что и `filter`.\n\n[Метод в документации](https://dashamail.ru/api/router/#list-routes)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 7, "priority": 0, "description": "Обращения в поддержку", "filter": { "combinator": "and", "conditions": [ { "field": "recipient", "op": "matches", "value": "^support@" } ] }, "expression": "recipient matches \"^support@\"", "actions": [ { "type": "webhook", "url": "https://example.ru/inbound", "attachments": "url" } ], "signing_key": "whsec_8f2c…", "is_active": true, "match_count": 412, "last_matched_at": "2026-04-12 09:41:02", "created_at": "2026-04-01 12:04:00", "updated_at": "2026-04-10 15:22:31" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "create-route", "summary": "Создать маршрут", "tags": [ "Обработка входящих" ], "description": "Создаёт правило обработки входящих писем. Без явного `priority` маршрут встаёт в конец очереди.\n\n> **Примечание.** Ключ подписи `signing_key` генерируется автоматически и возвращается в ответе — сохраните его, чтобы проверять подлинность webhook-запросов.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `actions` | JSON-строка, обязательный | Действия маршрута — от одного до пяти. См. [описание действий](https://dashamail.ru/api/router/#actions). |\n| `filter` | JSON-строка | Условия отбора писем. Несовместим с `expression`. Без условий маршрут принимает все письма. |\n| `expression` | string | Условия отбора текстом. Несовместим с `filter`. |\n| `description` | string | Описание маршрута, не длиннее 255 символов. |\n| `is_active` | флаг | Активен ли маршрут. По умолчанию: `1`. |\n| `priority` | integer | Порядок применения. Меньше — раньше. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Некорректная структура `filter` или `actions`, заданы оба способа задания условий, либо действие `forward` недоступно на текущем тарифе |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#create-route)", "responses": { "201": { "description": "Created", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 7, "priority": 0, "description": "Обращения в поддержку", "signing_key": "whsec_8f2c…", "is_active": true, "match_count": 0 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "actions": { "type": "string", "description": "Действия маршрута — от одного до пяти. См. [описание действий](https://dashamail.ru/api/router/#actions)." }, "filter": { "type": "string", "description": "Условия отбора писем. Несовместим с `expression`. Без условий маршрут принимает все письма." }, "expression": { "type": "string", "description": "Условия отбора текстом. Несовместим с `filter`." }, "description": { "type": "string", "description": "Описание маршрута, не длиннее 255 символов." }, "is_active": { "type": "string", "description": "Активен ли маршрут. Признак: передайте 1." }, "priority": { "type": "integer", "description": "Порядок применения. Меньше — раньше." } }, "required": [ "actions" ], "additionalProperties": true }, "example": { "description": "Обращения в поддержку", "filter": "{\"combinator\":\"and\",\"conditions\":[{\"field\":\"recipient\",\"op\":\"matches\",\"value\":\"^support@\"}]}", "actions": "[{\"type\":\"webhook\",\"url\":\"https://example.ru/inbound\",\"attachments\":\"url\"},{\"type\":\"stop\"}]" } } } } } }, "/router/routes/{route_id}": { "get": { "operationId": "get-route", "summary": "Один маршрут", "tags": [ "Обработка входящих" ], "description": "Возвращает маршрут целиком, включая ключ подписи.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Маршрута с таким идентификатором нет |\n\n[Метод в документации](https://dashamail.ru/api/router/#get-route)", "parameters": [ { "name": "route_id", "in": "path", "required": true, "description": "Идентификатор маршрута.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 7, "priority": 0, "description": "Обращения в поддержку", "filter": { "combinator": "and", "conditions": [ { "field": "recipient", "op": "matches", "value": "^support@" } ] }, "actions": [ { "type": "webhook", "url": "https://example.ru/inbound" } ], "signing_key": "whsec_8f2c…", "is_active": true } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update-route", "summary": "Изменить маршрут", "tags": [ "Обработка входящих" ], "description": "Меняет отдельные поля маршрута. Передавайте только то, что нужно изменить — незаданные поля сохраняют прежние значения.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `description` | string | Новое описание. |\n| `filter` | JSON-строка | Новые условия отбора. |\n| `expression` | string | Новые условия текстом. |\n| `actions` | JSON-строка | Новый набор действий. Заменяет прежний целиком. |\n| `is_active` | флаг | Включить или выключить маршрут. |\n| `priority` | integer | Новый порядок применения. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Маршрута с таким идентификатором нет |\n| `422` | `3` | Некорректные условия или действия |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#update-route)", "parameters": [ { "name": "route_id", "in": "path", "required": true, "description": "Идентификатор маршрута.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 7, "description": "Обращения в поддержку", "is_active": false } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "description": "Новое описание." }, "filter": { "type": "string", "description": "Новые условия отбора." }, "expression": { "type": "string", "description": "Новые условия текстом." }, "actions": { "type": "string", "description": "Новый набор действий. Заменяет прежний целиком." }, "is_active": { "type": "string", "description": "Включить или выключить маршрут. Признак: передайте 1." }, "priority": { "type": "integer", "description": "Новый порядок применения." } }, "additionalProperties": true }, "example": { "is_active": 0 } } } } }, "delete": { "operationId": "delete-route", "summary": "Удалить маршрут", "tags": [ "Обработка входящих" ], "description": "Удаляет маршрут. Уже сохранённые им письма остаются доступными до истечения их срока хранения.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Маршрута с таким идентификатором нет |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#delete-route)", "parameters": [ { "name": "route_id", "in": "path", "required": true, "description": "Идентификатор маршрута.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/routes/{route_id}/rekey": { "post": { "operationId": "rekey-route", "summary": "Перевыпустить ключ подписи", "tags": [ "Обработка входящих" ], "description": "Генерирует новый `signing_key`. Старый перестаёт действовать немедленно — обновите его в своём обработчике сразу после вызова.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Маршрута с таким идентификатором нет |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#rekey-route)", "parameters": [ { "name": "route_id", "in": "path", "required": true, "description": "Идентификатор маршрута.", "schema": { "type": "integer" }, "example": "7" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 7, "signing_key": "whsec_1d9b…" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/routes/reorder": { "post": { "operationId": "reorder-routes", "summary": "Изменить порядок маршрутов", "tags": [ "Обработка входящих" ], "description": "Задаёт новый порядок применения маршрутов одним запросом. Передайте идентификаторы в нужной последовательности.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `order` | JSON-строка, обязательный | Массив идентификаторов маршрутов в порядке применения. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Не передан `order` или он не является массивом |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#reorder-routes)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": true } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "order": { "type": "string", "description": "Массив идентификаторов маршрутов в порядке применения." } }, "required": [ "order" ], "additionalProperties": true }, "example": { "order": "[9,7,12]" } } } } } }, "/router/messages": { "get": { "operationId": "list-messages", "summary": "Сохранённые письма", "tags": [ "Обработка входящих" ], "description": "Письма, сохранённые действием `store`. Тело письма в список не входит — забирайте его [поштучно](https://dashamail.ru/api/router/#get-message).\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Писем по фильтру нет |\n\n[Метод в документации](https://dashamail.ru/api/router/#list-messages)", "parameters": [ { "name": "route_id", "in": "query", "required": false, "description": "Только письма указанного маршрута.", "schema": { "type": "integer" }, "example": 7 }, { "name": "recipient", "in": "query", "required": false, "description": "Фильтр по адресу получателя.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Письма, полученные не раньше.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "until", "in": "query", "required": false, "description": "Письма, полученные не позже.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" }, "example": 2 }, { "name": "offset", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 90211, "route_id": 7, "recipient": "support@mail.example.ru", "from_email": "ivan@example.com", "subject": "Не приходит счёт", "attachments_count": 1, "raw_size": 48213, "created_at": "2026-04-12 09:41:02", "expires_at": "2026-04-19 09:41:02", "retrieved_at": null } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/messages/{message_id}": { "get": { "operationId": "get-message", "summary": "Одно письмо", "tags": [ "Обработка входящих" ], "description": "Возвращает разобранное письмо: заголовки, текстовую и HTML-версии, перечень вложений.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Письма с таким идентификатором нет или срок хранения истёк |\n\n[Метод в документации](https://dashamail.ru/api/router/#get-message)", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Идентификатор письма.", "schema": { "type": "integer" }, "example": "90211" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 90211, "route_id": 7, "recipient": "support@mail.example.ru", "sender": "ivan@example.com", "from_email": "ivan@example.com", "message_id_header": "Здравствуйте! Счёт по заказу 1024 так и не пришёл.
", "attachments_count": 1, "raw_size": 48213, "created_at": "2026-04-12 09:41:02", "expires_at": "2026-04-19 09:41:02" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "delete-message", "summary": "Удалить письмо", "tags": [ "Обработка входящих" ], "description": "Удаляет сохранённое письмо вместе с вложениями, не дожидаясь истечения срока хранения.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Письма с таким идентификатором нет |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#delete-message)", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Идентификатор письма.", "schema": { "type": "integer" }, "example": "90211" } ], "responses": { "204": { "description": "No Content" }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/messages/{message_id}/attachments/{attachment_id}": { "get": { "operationId": "get-attachment", "summary": "Вложение письма", "tags": [ "Обработка входящих" ], "description": "Возвращает вложение письма — имя файла, MIME-тип и содержимое.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `400` | `400` | Не указан идентификатор вложения |\n| `404` | `9` | Вложение не найдено |\n\n[Метод в документации](https://dashamail.ru/api/router/#get-attachment)", "parameters": [ { "name": "message_id", "in": "path", "required": true, "description": "Идентификатор письма.", "schema": { "type": "integer" }, "example": "90211" }, { "name": "attachment_id", "in": "path", "required": true, "description": "Идентификатор вложения.", "schema": { "type": "integer" }, "example": "1" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 1, "message_id": 90211, "filename": "order-1024.pdf", "mime_type": "application/pdf", "size": 44120, "body": "JVBERi0xLjQKJcfs…" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/deliveries": { "get": { "operationId": "list-deliveries", "summary": "Журнал доставок webhook", "tags": [ "Обработка входящих" ], "description": "Попытки доставки писем на ваши webhook-адреса и адреса пересылки. Первое место, куда стоит смотреть, если письма до вашей системы не доходят.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Доставок по фильтру нет |\n\n[Метод в документации](https://dashamail.ru/api/router/#list-deliveries)", "parameters": [ { "name": "route_id", "in": "query", "required": false, "description": "Только доставки указанного маршрута.", "schema": { "type": "integer" } }, { "name": "status", "in": "query", "required": false, "description": "Фильтр по результату доставки.", "schema": { "type": "string" }, "example": "failed" }, { "name": "recipient", "in": "query", "required": false, "description": "Фильтр по адресу получателя исходного письма.", "schema": { "type": "string" } }, { "name": "since", "in": "query", "required": false, "description": "Не раньше указанного момента.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "until", "in": "query", "required": false, "description": "Не позже указанного момента.", "schema": { "type": "string", "example": "2026-03-14 11:02:41" } }, { "name": "limit", "in": "query", "required": false, "description": "Размер страницы.", "schema": { "type": "integer" }, "example": 2 }, { "name": "offset", "in": "query", "required": false, "description": "Смещение.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": [ { "id": 55120, "route_id": 7, "message_id": 90211, "status": "failed", "http_code": 502, "attempts": 3, "created_at": "2026-04-12 09:41:05" } ] } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/deliveries/{delivery_id}": { "get": { "operationId": "get-delivery", "summary": "Одна доставка", "tags": [ "Обработка входящих" ], "description": "Подробности попытки доставки, включая ответ вашего сервера — по нему видно, почему запрос не прошёл.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `404` | `4` | Доставки с таким идентификатором нет |\n\n[Метод в документации](https://dashamail.ru/api/router/#get-delivery)", "parameters": [ { "name": "delivery_id", "in": "path", "required": true, "description": "Идентификатор доставки.", "schema": { "type": "integer" }, "example": "55120" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "id": 55120, "route_id": 7, "message_id": 90211, "status": "failed", "http_code": 502, "attempts": 3, "response_body": "502 Bad Gateway", "created_at": "2026-04-12 09:41:05" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/router/settings": { "get": { "operationId": "get-router-settings", "summary": "Настройки обработки", "tags": [ "Обработка входящих" ], "description": "Общие настройки приёма входящей почты.\n\n[Метод в документации](https://dashamail.ru/api/router/#get-router-settings)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "pass_autoreply": 0, "pass_list_mail": 0 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "update-router-settings", "summary": "Изменить настройки", "tags": [ "Обработка входящих" ], "description": "Задаёт, пропускать ли служебную почту к вашим маршрутам. По умолчанию автоответы и рассылочные письма отфильтровываются: это защищает от петель, когда ваш обработчик отвечает на автоответ, а тот отвечает снова.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `pass_autoreply` | флаг | Пропускать автоответы («в отпуске», «получено»). По умолчанию: `0`. |\n| `pass_list_mail` | флаг | Пропускать письма с заголовками рассылок (`List-Id` и подобными). По умолчанию: `0`. |\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `401` | `2` | Недостаточно прав |\n\n[Метод в документации](https://dashamail.ru/api/router/#update-router-settings)", "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "pass_autoreply": 1, "pass_list_mail": 0 } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "pass_autoreply": { "type": "string", "description": "Пропускать автоответы («в отпуске», «получено»). Признак: передайте 1." }, "pass_list_mail": { "type": "string", "description": "Пропускать письма с заголовками рассылок (`List-Id` и подобными). Признак: передайте 1." } }, "additionalProperties": true }, "example": { "pass_autoreply": 1, "pass_list_mail": 0 } } } } } }, "/images/optimize": { "post": { "operationId": "optimize-image", "summary": "Оптимизировать изображение", "tags": [ "Изображения" ], "description": "Принимает JPEG, PNG или GIF и возвращает облегчённую версию в том же формате вместе со статистикой: сколько весило, сколько стало и какие шаги сработали.\n\nЕсли ужать не удалось — картинка уже оптимальна, нужного кодека нет на сервере или результат получился больше исходника, — метод возвращает файл без изменений и `changed: false`. Ошибкой это не считается.\n\n> **Примечание.** **Как передать картинку.** Либо полем `image` в JSON — строка base64, допускается префикс `data:image/png;base64,`. Либо как файл в `multipart/form-data`, поле `file`:\n>\n> ```\n> curl -X POST 'https://api.dashamail.com/v2/images/optimize' \\\n> -H 'Authorization: Bearer YOUR_API_KEY' \\\n> -F 'file=@photo.jpg'\n> ```\n>\n> Второй способ предпочтителен для крупных файлов: base64 раздувает тело запроса примерно на треть.\n\n**Параметры тела запроса**\n\n| Параметр | Тип | Описание |\n| --- | --- | --- |\n| `image` | string | Картинка в base64. Не нужен, если файл передан через `multipart/form-data`. |\n| `resize` | флаг | Ужимать ли по ширине. По умолчанию включено; `0` оставит исходную геометрию и выполнит только пережатие. |\n| `max_width` | integer | Другой потолок ширины вместо 1600 px. Допустимо от 16 до 20000. |\n| `lossy` | флаг | Разрешить пережатие с потерями. Даёт заметно меньший файл ценой небольшой потери качества; по умолчанию выключено. |\n\n**Что возвращается**\n\nОптимизированную картинку в base64 (поле `image`) и статистику обработки. Поле `steps` показывает, что сработало на каждом из двух шагов, — полезно, когда результат не совпал с ожиданием.\n\n**Возможные ошибки**\n\n| HTTP | `code` | Когда возникает |\n| --- | --- | --- |\n| `422` | `3` | Картинка не передана, `image` не является корректным base64, формат не JPEG/PNG/GIF либо `max_width` вне диапазона 16–20000 |\n| `413` | `26` | Картинка тяжелее 20 МиБ |\n\n[Метод в документации](https://dashamail.ru/api/images/#optimize-image)", "parameters": [ { "name": "response", "in": "query", "required": false, "description": "Со значением `binary` метод отдаёт сами байты картинки с соответствующим `Content-Type`, а статистику кладёт в заголовки `X-Imageopt-Original-Size`, `X-Imageopt-Size` и `X-Imageopt-Saved-Bytes`. По умолчанию ответ приходит в обычном JSON-конверте.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "response": { "msg": { "err_code": 0, "text": "OK", "type": "message" }, "data": { "format": "png", "mime": "image/png", "changed": true, "steps": { "resize": "already_narrow", "compress": "pngquant" }, "width": 900, "height": 600, "original_width": 900, "original_height": 600, "original_size": 812345, "size": 279431, "saved_bytes": 532914, "saved_percent": 65.6, "image": "iVBORw0KGgoAAAANSUhEUgAAA…" } } } } } }, "default": { "description": "Ошибка. Код в error.code точнее HTTP-статуса.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "image": { "type": "string", "description": "Картинка в base64. Не нужен, если файл передан через `multipart/form-data`." }, "resize": { "type": "string", "description": "Ужимать ли по ширине. По умолчанию включено; `0` оставит исходную геометрию и выполнит только пережатие. Признак: передайте 1." }, "max_width": { "type": "integer", "description": "Другой потолок ширины вместо 1600 px. Допустимо от 16 до 20000." }, "lossy": { "type": "string", "description": "Разрешить пережатие с потерями. Даёт заметно меньший файл ценой небольшой потери качества; по умолчанию выключено. Признак: передайте 1." } }, "additionalProperties": true }, "example": { "image": "iVBORw0KGgoAAAANSUhEUgAAA…", "lossy": 1 } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Заголовок Authorization: Bearer <ключ>. Основной способ." }, "apiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key", "description": "Ключ параметром строки запроса. Проще, но адрес попадает в логи прокси и веб-серверов." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "integer", "description": "Код ошибки DashaMail. Точнее HTTP-статуса: одному статусу соответствует несколько кодов." }, "message": { "type": "string" } } } } } } } }