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

Что здесь. Письма, которые приходят на любой адрес домена сайта (info@, sales@, support@), сшиваются в переписки. Отсюда их читают, отвечают письмом, убирают в архив и держат шаблоны ответа. В дашборде это раздел «Входящие», настройки ящика — «Настройки → Почта сайта». Каждая ручка, поле и код отказа на этой странице сверены с кодом; чтение, отметки и настройки прогнаны вызовом на тестовом сайте.

Адреса. Ручки сайта: https://onpress.pro/api/v2/site/{siteId}/inbox/…, права — администратор сайта или суперадмин сети. В примерах op_XXXX — ваш токен, SITE_ID — внешний идентификатор сайта (поле site_id ответа GET /sites/{id}). Как выбирается сайт и в какой форме приходят отказы — доступ.

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

Переписки

Пункт	Ручка	Тело
Список	`GET /inbox/threads`	`?archived=0&unread=1&q=…`
Ящики и счётчики	`GET /inbox/filters`	—
Счётчик непрочитанных	`GET /inbox/unread-count`	—
Прочитать всё	`POST /inbox/read-all`	`{}`
Переписка с письмами	`GET /inbox/threads/{id}`	`?mark_read=0`
Архив и «прочитано»	`PATCH /inbox/threads/{id}`	`{"archived": true}`, `{"read": false}`
Письмо как пришло	`GET /inbox/threads/{id}/messages/{mid}/html`	—
Исходник письма	`GET /inbox/messages/{id}/raw`	—
Вложение	`GET /inbox/attachments/{id}`	—

Список

Параметры, все необязательные:

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

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

{
  "id": 7,
  "blog_id": 233,
  "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": ""
}

last_direction — чьё последнее письмо: in собеседника, out наше. Непустой external_ref значит, что переписка ведётся в Framesuite: здесь она только для чтения, ответ отказывает 409 thread_read_only. Неизвестный sort — 400 invalid_sort.

curl -s "https://onpress.pro/api/v2/site/SITE_ID/inbox/threads?unread=1" -H "Authorization: Bearer op_XXXX"

Ящики и счётчики

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

Счётчик непрочитанных

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

Прочитать всё

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

Переписка с письмами

Ответ — thread и messages по порядку. Чтение снимает «непрочитано»; ?mark_read=0 — прочитать, не снимая. Письмо: direction (in или out), from (email, name), to, cc, subject, body_text, has_html, attachments (id, name, mime, size, stored), mail_status (inbound, sending, sent, draft, failed), mail_error, mail_error_code, template_ids, created_at. Чужая или несуществующая переписка — 404 thread_not_found, одинаково.

Архив и «прочитано»

Тело — любое из двух полей или оба: archived (true — в архив, false — во входящие), read (false — отметить непрочитанной, true — прочитанной). Ответ — {"success": true, "thread": {…}}. Пустое тело — 400 nothing_to_update.

curl -s -X PATCH "https://onpress.pro/api/v2/site/SITE_ID/inbox/threads/7" \
  -H "Authorization: Bearer op_XXXX" -H "Content-Type: application/json" \
  -d '{"read": false}'

То же для «прочитано» умеет и прежняя POST /inbox/threads/{id}/read с телом {"read": false}.

Письмо как пришло

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

Исходник и вложение

Исходник — файл .eml из архива почты, только у полученных писем; иначе 404 raw_not_found. Вложение — файл с заголовком скачивания; id вида <письмо>-<номер> из attachments письма. Файла нет или он не был сохранён (письмо пришло с описью без содержимого) — 404 attachment_not_found.

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

Пункт	Ручка	Тело
Ответить	`POST /inbox/threads/{id}/reply`	`{"body": "…", "attachments": ["upl_…"], "template_ids": [3]}`
Загрузить вложение	`POST /inbox/uploads`	`{"name": "a.pdf", "mime": "application/pdf", "content": "base64"}`
Повторить неушедшее	`POST /inbox/messages/{id}/retry`	`{}`
С какого адреса уйдёт ответ	`GET /inbox/sender`	—

Ответить

Поля: body — текст ответа, до 100 000 знаков; attachments — токены загрузок, до 10 и не больше 7 МБ на письмо; template_ids — какие шаблоны ответа применены (для счётчика применений). Нужен текст или хотя бы одно вложение. Подпись из настроек ящика дописывается в конец текста. Ответ уходит собеседнику с темой «Re: …» и правильными ссылками на предыдущие письма, так что в его почте он ложится в ту же цепочку. Переписка становится прочитанной и не меняет папку.

Исход	Код	Что значит
Отправлено	200, `status: "sent"`	письмо ушло
Черновик	409 `sender_not_verified`	отправка с адреса сайта ещё не включена; письмо сохранено черновиком с `state`, повторяется ручкой «Повторить»
Не ушло	502 или 422 `send_failed`	`retryable` — стоит ли повторять; письмо сохранено в переписке
Пусто	400 `empty_reply`	нет ни текста, ни вложений
Длинно	400 `body_too_long`	больше 100 000 знаков
Некому	422 `no_recipient`	у переписки нет адреса собеседника
Только чтение	409 `thread_read_only`	переписка ведётся в Framesuite

В черновике и отказе приходят draft (сохранённое письмо) и thread.

Загрузить вложение

content — файл в base64. Ответ — {"success": true, "upload": {"token": "upl_…", "name": "a.pdf", "mime": "application/pdf", "size": 1024}}; токен идёт в attachments ответа. Отказы: 400 invalid_upload (нет или пустое содержимое, не тот токен), 413 attachment_too_large, 400 too_many_attachments, 400 upload_not_found (токен истёк).

Повторить неушедшее

Только наши письма в draft или failed; отправитель пересчитывается заново. Иначе 400 not_outgoing или 409 not_retryable. Исходы — те же, что у ответа.

С какого адреса уйдёт ответ

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

Ответы уходят с личного адреса сайта на домене площадки: <имя-сайта>-<SITE_ID>@onpress.pro. Ответ собеседника на него возвращается в ту же переписку. ready — готова ли отправка по итогу последней попытки: true, false или null (ещё не отправляли); state — ready, not_verified, identity_missing или unknown.

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

Пункт	Ручка	Тело
Настройки	`GET /inbox/settings` `PATCH /inbox/settings`	`{"from_name": "…", "signature": "…"}`

Настройки

Ответ:

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

Меняются два поля, остальное только для чтения:

from_name — имя отправителя, которое собеседник видит рядом с адресом, до 120 знаков, без <, >, " и @. Пустая строка — название сайта.

signature — подпись, которая дописывается в конец каждого ответа через пустую строку, до 2000 знаков. Пустая строка — без подписи.

domains — домены, письма на которые попадают в этот сайт: подходит любой адрес на них. mailboxes — адреса, на которые уже писали, с числом переписок. sender — то же, что GET /inbox/sender.

Ответ PATCH — те же настройки целиком. Отказы: 400 invalid_from_name, 400 invalid_signature, 400 nothing_to_update (нет ни одного поля).

curl -s -X PATCH "https://onpress.pro/api/v2/site/SITE_ID/inbox/settings" \
  -H "Authorization: Bearer op_XXXX" -H "Content-Type: application/json" \
  -d '{"from_name": "Поддержка", "signature": "С уважением,\nкоманда сайта"}'

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

Пункт	Ручка	Тело
Список	`GET /inbox/templates`	`?all=1&order=usage`
Создать	`POST /inbox/templates`	`{"title": "Спасибо", "body": "…"}`
Изменить	`PUT /inbox/templates/{id}`	`{"quick_reply": true}`
Удалить	`DELETE /inbox/templates/{id}`	—
Зачесть применение	`POST /inbox/templates/{id}/used`	`{}`

Список

Шаблоны сайта и общие шаблоны сети (blog_id: 0). По умолчанию только включённые; all=1 — все. order: sort (по умолчанию), usage (чаще применяемые первыми), title. Шаблон: id, scope (site или network), blog_id, title, body, locale, category, sort, is_active, quick_reply, usage_count, last_used_at.

Создать, изменить, удалить

Поля: title (обязательно, до 190 знаков), body (обязательно, до 20 000 знаков), locale, category, sort, is_active — показывать в полосе шаблонов под полем ответа, quick_reply — кнопка под полем ответа, которая сразу отправляет этот текст. Менять и удалять можно только шаблоны своего сайта; чужой или сетевой — 404 template_not_found. Неверные поля — 400 invalid_template, пустой PUT — 400 nothing_to_update. Сетевые шаблоны правит только суперадмин сети.

Зачесть применение

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