Справочник: входящие

Здесь все эндпоинты /site/$SITE/inbox… с параметрами, ответами и отказами: письма на любой адрес домена сайта (info@, sales@, support@) сшиваются в переписки, отсюда их читают, отвечают письмом и держат шаблоны ответа; в консоли это раздел «Входящие», настройки ящика — «Настройки → Почта сайта».

Во всех примерах API — https://onpress.pro/api/v2, SITE — id сайта (SITE_ID), OP_TOKEN — токен op_XXXX. Все эндпоинты страницы пишутся от /site/$SITE и доступны администратору сайта. Как получить токен и в какой форме приходят отказы — на странице «Доступ и токен».

Как устроена переписка

У переписки два признака: прочитана она или нет (unread) и лежит во входящих или в архиве (archived); статусов «открыта» и «закрыта» нет. Новое письмо делает переписку непрочитанной и возвращает её из архива во входящие. Чужая и несуществующая переписка отвечают одинаково — 404 thread_not_found.

Переписки

GET /inbox/threads

Отдаёт список переписок с отбором, поиском и сортировкой. Ответ — threads, total, page, per_page и unread_count (непрочитанные во входящих, без архива). Например, только непрочитанные:

curl -s "$API/site/$SITE/inbox/threads?unread=1" -H "Authorization: Bearer $OP_TOKEN"

Параметр	Тип	По умолчанию	Описание
`archived`	string	`0`	`0` — входящие, `1` — архив, `all` — всё
`unread`	string	все	`1` — только непрочитанные, `0` — только прочитанные
`mailbox`	string	все	адрес ящика, на который писали
`has_attachments`	string	все	`1` или `0`
`q`	string	—	поиск по теме, адресу и имени собеседника, началу письма
`sort`	string	`last_message_at`	`last_message_at`, `created_at`, `messages_count`, `contact`
`dir`	string	`desc`	`desc` или `asc`
`page`	int	`1`	номер страницы
`per_page`	int	`30`	до 200

{
  "id": 7,
  "site_id": "x9HTLHECq",
  "domain": "example.com",
  "mailbox": "info@example.com",
  "subject": "Вопрос по заказу",
  "archived": false,
  "unread": true,
  "contact": { "email": "client@example.org", "name": "Анна" },
  "messages_count": 1,
  "preview": "Добрый день! …",
  "has_attachments": false,
  "last_direction": "in",
  "last_message_at": "2026-10-02T17:44:19Z",
  "created_at": "2026-10-02T17:44:19Z",
  "updated_at": "2026-10-02T19:22:38Z",
  "resolved_by": "mail_domain",
  "external_ref": ""
}

Поле	Описание
`domain`, `mailbox`	домен и адрес, на который написали
`contact`	собеседник: `email`, `name`
`preview`	начало последнего письма
`last_direction`	чьё последнее письмо: `in` — собеседника, `out` — наше
`resolved_by`	как письмо нашло сайт; `mail_domain` — по домену адреса
`external_ref`	непустой — переписка ведётся во внешней службе поддержки: здесь она только для чтения, ответ отказывает `409 thread_read_only`

Код	Статус	Когда	Что делать
`invalid_sort`	400	неизвестный `sort`	возьмите значение из таблицы

GET /inbox/filters

Отдаёт ящики и счётчики для боковой панели. mailboxes — ящики, на которые уже писали, с числом переписок threads и непрочитанных unread; counts — inbox (во входящих), archived (в архиве), unread; плюс unread_count и has_unread. Например:

curl -s "$API/site/$SITE/inbox/filters" -H "Authorization: Bearer $OP_TOKEN"

{ "mailboxes": [ { "mailbox": "info@example.com", "threads": 1, "unread": 0 } ], "counts": { "inbox": 1, "archived": 0, "unread": 0 }, "unread_count": 0, "has_unread": false }

GET /inbox/unread-count

Отдаёт число непрочитанных переписок во входящих, архив не считается: {"unread_count": 3}. По нему консоль рисует число у пункта меню. Например:

curl -s "$API/site/$SITE/inbox/unread-count" -H "Authorization: Bearer $OP_TOKEN"

POST /inbox/read-all

Снимает «непрочитано» со всех переписок сайта; тело не читается. Ответ — {"success": true, "updated": 3}. Например:

curl -s -X POST "$API/site/$SITE/inbox/read-all" -H "Authorization: Bearer $OP_TOKEN"

GET /inbox/threads/{id}

Отдаёт переписку thread и её письма messages по порядку. Чтение снимает «непрочитано»; ?mark_read=0 — прочитать, не снимая. Например:

curl -s "$API/site/$SITE/inbox/threads/7?mark_read=0" -H "Authorization: Bearer $OP_TOKEN"

Поле письма	Описание
`direction`	`in` — от собеседника, `out` — наше
`from`, `to`, `cc`	отправитель (`email`, `name`) и получатели
`subject`, `body_text`	тема и текст
`has_html`	есть ли HTML-часть — её отдаёт `GET …/messages/{mid}/html`
`attachments`	вложения: `id`, `name`, `mime`, `size`, `stored` — сохранён ли файл
`mail_status`	`inbound`, `sending`, `sent`, `draft`, `failed`
`mail_error`, `mail_error_code`	почему наше письмо не ушло
`template_ids`	какие шаблоны применены в ответе
`created_at`	время письма

Код	Статус	Когда	Что делать
`thread_not_found`	404	переписки нет на этом сайте	проверьте `{id}`

PATCH /inbox/threads/{id}

Убирает переписку в архив или возвращает во входящие и ставит отметку «прочитано»; передайте одно поле или оба. Ответ — {"success": true, "thread": {…}}. Например, отметить непрочитанной:

curl -s -X PATCH "$API/site/$SITE/inbox/threads/7" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"read": false}'

Поле	Тип	По умолчанию	Описание
`archived`	bool	—	`true` — в архив, `false` — во входящие
`read`	bool	—	`true` — прочитана, `false` — непрочитана

Код	Статус	Когда	Что делать
`nothing_to_update`	400	нет ни одного поля	передайте `archived` или `read`
`thread_not_found`	404	переписки нет на этом сайте	проверьте `{id}`

GET /inbox/threads/{id}/messages/{mid}/html

Отдаёт HTML письма как оно пришло, без обработки: {"message_id": 10, "thread_id": 7, "html": "…"}; html: null — HTML-части не было. Показывайте его только в изолированной рамке без скриптов: содержимое чужое. Например:

curl -s "$API/site/$SITE/inbox/threads/7/messages/10/html" -H "Authorization: Bearer $OP_TOKEN"

Код	Статус	Когда	Что делать
`message_not_found`	404	письма нет в этой переписке	проверьте `{mid}`

GET /inbox/messages/{id}/raw

Отдаёт исходник письма файлом .eml (message/rfc822) — только у полученных писем. Например:

curl -s -o letter.eml "$API/site/$SITE/inbox/messages/10/raw" -H "Authorization: Bearer $OP_TOKEN"

Код	Статус	Когда	Что делать
`raw_not_found`	404	исходника нет: письмо наше или не сохранено	—

GET /inbox/attachments/{id}

Отдаёт вложение файлом с заголовком скачивания. {id} вида <письмо>-<номер> — из attachments письма. Например:

curl -s -OJ "$API/site/$SITE/inbox/attachments/10-1" -H "Authorization: Bearer $OP_TOKEN"

Код	Статус	Когда	Что делать
`attachment_not_found`	404	файла нет или он не был сохранён: письмо пришло с описью без содержимого (`stored: false`)	—

Ответ письмом

POST /inbox/threads/{id}/reply

Отправляет ответ собеседнику с темой «Re: …» и ссылками на предыдущие письма, так что в его почте он ложится в ту же цепочку. Нужен текст или хотя бы одно вложение; подпись из настроек ящика дописывается в конец текста. Переписка становится прочитанной и остаётся в своей папке. Например:

curl -s -X POST "$API/site/$SITE/inbox/threads/7/reply" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"body": "Добрый день! Заказ отправлен сегодня.", "template_ids": [3]}'

Поле	Тип	По умолчанию	Описание
`body`	string	`""`	текст ответа, до 100 000 знаков
`attachments`	array	`[]`	токены из `POST /inbox/uploads`, до 10 и не больше 7 МБ на письмо
`template_ids`	array	`[]`	какие шаблоны применены — для счётчика применений

Ушедший ответ — 200 с status: "sent". В отказах ниже, кроме 400, приходят draft — сохранённое письмо — и thread.

Код	Статус	Когда	Что делать
`empty_reply`	400	нет ни текста, ни вложений	передайте `body` или `attachments`
`body_too_long`	400	текст длиннее 100 000 знаков	сократите
`too_many_attachments`	400	больше 10 вложений	уберите лишние
`invalid_upload`, `upload_not_found`	400	токен не из `POST /inbox/uploads` или истёк	загрузите файл заново
`attachment_too_large`	413	вложений больше 7 МБ	уберите лишние
`thread_not_found`	404	переписки нет на этом сайте	проверьте `{id}`
`sender_not_verified`	409	отправка с адреса сайта ещё не включена; письмо сохранено черновиком, в ответе `state`	повторите через `POST /inbox/messages/{id}/retry`
`thread_read_only`	409	переписка ведётся во внешней службе поддержки	—
`no_recipient`	422	у переписки нет адреса собеседника	—
`send_failed`	422 или 502	письмо не ушло, сохранено в переписке; `retryable` — стоит ли повторять, `mail_error_code` — причина	при `retryable: true` повторите через `retry`

POST /inbox/uploads

Загружает файл для вложения в ответ и отдаёт токен, который идёт в attachments. Ответ — {"success": true, "upload": {"token": "upl_…", "name": "a.pdf", "mime": "application/pdf", "size": 1024}}. Например:

curl -s -X POST "$API/site/$SITE/inbox/uploads" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"name": "a.pdf", "mime": "application/pdf", "content": "JVBERi0xLjQK…"}'

Поле	Тип	По умолчанию	Описание
`name`	string	—	имя файла
`mime`	string	—	тип файла
`content`	string	—	файл в base64, до 7 МБ

Код	Статус	Когда	Что делать
`invalid_upload`	400	нет `content`, он пустой или не base64	передайте файл в base64
`attachment_too_large`	413	файл больше 7 МБ	уменьшите файл

POST /inbox/messages/{id}/retry

Повторяет отправку нашего письма в draft или failed; отправитель выбирается заново, тело не читается. Исходы и отказы — как у ответа. Например:

curl -s -X POST "$API/site/$SITE/inbox/messages/12/retry" -H "Authorization: Bearer $OP_TOKEN"

Код	Статус	Когда	Что делать
`not_outgoing`	400	письмо не наше	—
`not_retryable`	409	письмо не в `draft` и не в `failed`	—

GET /inbox/sender

Отдаёт, с какого адреса уйдёт ответ. Ответы уходят с личного адреса сайта на домене платформы, <имя-сайта>-<site_id>@onpress.pro, и ответ собеседника на него возвращается в ту же переписку. Например:

curl -s "$API/site/$SITE/inbox/sender" -H "Authorization: Bearer $OP_TOKEN"

{ "from": "mysite-x9htlhecq@onpress.pro", "from_name": "Мой сайт", "site_address": "mysite-x9htlhecq@onpress.pro", "reply_to": "mysite-x9htlhecq@onpress.pro", "domain": "onpress.pro", "platform_domain": "onpress.pro", "ready": null, "state": "unknown", "checked_at": null }

Поле	Описание
`from`, `from_name`	адрес и имя отправителя
`reply_to`	куда придёт ответ собеседника
`ready`	готова ли отправка по итогу последней попытки: `true`, `false` или `null` — ещё не отправляли
`state`	`ready`, `not_verified`, `identity_missing` или `unknown`
`checked_at`	когда проверяли

Настройки ящика

GET /inbox/settings

Отдаёт имя отправителя, подпись, пределы полей, домены сайта, приём почты на них, ящики и отправителя. Например:

curl -s "$API/site/$SITE/inbox/settings" -H "Authorization: Bearer $OP_TOKEN"

{
  "success": true,
  "settings": { "from_name": "", "signature": "", "updated_at": null },
  "limits": { "from_name": 120, "signature": 2000 },
  "domains": ["example.com"],
  "reception": [ { "domain": "example.com", "state": "catch_all", "mx": ["mail.onpress.pro"], "catch_all": "info@example.com" } ],
  "mailboxes": [ { "address": "info@example.com", "threads": 1, "last_message_at": "2026-10-02T17:44:19Z" } ],
  "sender": { "from": "mysite-x9htlhecq@onpress.pro", "from_name": "Мой сайт", "ready": null, "state": "unknown" }
}

Поле	Описание
`domains`	домены, письма на которые попадают в этот сайт: подходит любой адрес на них
`reception`	приём почты по каждому домену: `state` — `catch_all` (почта принимается, все адреса собирает ящик `catch_all`), `platform` (MX ведёт на платформу, сбор писем не настроен), `external` (MX ведёт на чужой почтовый сервер), `no_mx` (у домена нет MX), `unknown` (проверить не удалось); `mx` — MX-записи домена
`mailboxes`	адреса, на которые уже писали, с числом переписок
`sender`	то же, что `GET /inbox/sender`

PATCH /inbox/settings

Меняет имя отправителя и подпись; остальные поля настроек только для чтения. Ответ — настройки целиком, как у GET /inbox/settings. Например:

curl -s -X PATCH "$API/site/$SITE/inbox/settings" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"from_name": "Поддержка", "signature": "С уважением,\nкоманда сайта"}'

Поле	Тип	По умолчанию	Описание
`from_name`	string	название сайта	имя рядом с адресом отправителя, до 120 знаков, без `<`, `>`, `"` и `@`; `""` — название сайта
`signature`	string	`""`	подпись в конце каждого ответа через пустую строку, до 2000 знаков; `""` — без подписи

Код	Статус	Когда	Что делать
`nothing_to_update`	400	нет ни одного поля	передайте `from_name` или `signature`
`invalid_from_name`	400	длиннее 120 знаков или с запрещёнными символами	исправьте поле
`invalid_signature`	400	длиннее 2000 знаков	сократите

Шаблоны ответа

GET /inbox/templates

Отдаёт шаблоны сайта (scope: "site") и общие шаблоны платформы (scope: "network"). Например, все шаблоны, частые первыми:

curl -s "$API/site/$SITE/inbox/templates?all=1&order=usage" -H "Authorization: Bearer $OP_TOKEN"

Параметр	Тип	По умолчанию	Описание
`all`	string	—	`1` — и выключенные; без него только `is_active`
`order`	string	`sort`	`sort`, `usage` — чаще применяемые первыми, `title`

Шаблон: id, scope, title, body, locale, category, sort, is_active, quick_reply, usage_count, last_used_at.

POST /inbox/templates

Создаёт шаблон сайта. Ответ — {"success": true, "template": {…}}. Например:

curl -s -X POST "$API/site/$SITE/inbox/templates" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"title": "Спасибо", "body": "Спасибо за письмо! Ответим в течение дня."}'

Поле	Тип	По умолчанию	Описание
`title`	string	—	название, до 190 знаков
`body`	string	—	текст, до 20 000 знаков
`locale`	string	`""`	язык шаблона
`category`	string	`""`	группа в списке
`sort`	int	`0`	порядок в списке
`is_active`	bool	`true`	показывать в полосе шаблонов под полем ответа
`quick_reply`	bool	`false`	кнопка под полем ответа, которая сразу отправляет этот текст

Код	Статус	Когда	Что делать
`invalid_template`	400	нет `title` или `body`, или они длиннее предела	исправьте поля

PUT /inbox/templates/{id}

Меняет переданные поля шаблона сайта; поля — как у создания, ответ — {"success": true, "template": {…}}. Например, сделать шаблон быстрым ответом:

curl -s -X PUT "$API/site/$SITE/inbox/templates/3" \
  -H "Authorization: Bearer $OP_TOKEN" -H 'Content-Type: application/json' \
  -d '{"quick_reply": true}'

Код	Статус	Когда	Что делать
`nothing_to_update`	400	пустое тело	передайте поле
`invalid_template`	400	неверное поле	исправьте поле
`template_not_found`	404	шаблона нет, он чужой или общий	меняются только шаблоны своего сайта

DELETE /inbox/templates/{id}

Удаляет шаблон сайта. Ответ — {"success": true, "deleted": 3}. Например:

curl -s -X DELETE "$API/site/$SITE/inbox/templates/3" -H "Authorization: Bearer $OP_TOKEN"

Код	Статус	Когда	Что делать
`template_not_found`	404	шаблона нет, он чужой или общий	удаляются только шаблоны своего сайта

POST /inbox/templates/{id}/used

Увеличивает usage_count шаблона, ответ — шаблон в template. Обычно не нужен: ответ с template_ids засчитывает применение сам, когда письмо ушло. Например:

curl -s -X POST "$API/site/$SITE/inbox/templates/3/used" -H "Authorization: Bearer $OP_TOKEN"

Общие отказы

Код	Статус	Когда	Что делать
`mail_domain_unreadable`	502	не удалось прочитать настройки почтового домена	повторите позже
`mail_not_configured`	503	почта на сервере не подключена	напишите в поддержку