---
title: "Получить письма по фильтру"
method: GET
path: "/api/v1/mail/messages"
tags: ["Mail messages"]
---

# Получить письма по фильтру

`GET /api/v1/mail/messages`

## Request

- Base URL: `https://erp.akeda.ru`
- URL: `https://erp.akeda.ru/api/v1/mail/messages`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://erp.akeda.ru/oauth2/authorize`, token URL `https://erp.akeda.ru/oauth2/token`, scopes: `akeda:delegate`)

Одна выборка обслуживает и список папки, и поиск. Папку можно назвать ролью (folder_role), не зная её идентификатора: так инструкция агента переносится между кабинетами. Видны письма только тех ящиков, которые доступны сотруднику.

## Query parameters

- `q` string
- `account_id` string, uuid
- `folder_id` string, uuid
- `thread_id` string, uuid
- `folder_role` 'inbox' | 'outbox' | 'sent' | 'drafts' | 'trash' | 'spam' | 'archive' | 'custom': Назначение папки в нашем прочтении, а не её имя на сервере. Незнакомое имя остаётся custom — угаданная роль складывала бы туда отправленные письма.
- `from` string
- `spam_verdict` 'unknown' | 'spam' | 'ham': Вердикт по спаму; unknown — состояние по умолчанию. Вердикт справочный и с папкой не связан: письмо во «Входящих» может нести spam от провайдера (флаг $Junk на сервере почты), а папку «Спам» задаёт только перенос. Решение человека (spam_source=user) сильнее флага сервера и правил.
- `is_read` boolean
- `is_flagged` boolean
- `has_files` boolean
- `sent_after` string, date-time
- `sent_before` string, date-time
- `limit` integer
- `offset` integer
- `all_mail` boolean

## Headers

- `X-Tenant` string, required

## Response `200`

Страница писем с общим числом строк

- MailMessagePage: Страница писем. Общее число нужно, чтобы решить, стоит ли листать дальше.
  - `items` MailMessage[], required
    - `id` string, uuid, required
    - `account_id` string, uuid, required
    - `folder_id` string, uuid, required
    - `thread_id` string, uuid, required
    - `message_ref` string, required: Message-ID без угловых скобок; письму без него присваивается наш
    - `in_reply_to` string: Заголовок In-Reply-To
    - `references` string: Заголовок References целиком
    - `subject` string, required
    - `from_address` string, required
    - `from_name` string, required
    - `addresses` MailMessageAddress[]: Конверт письма целиком
      - `kind` string, required: Вид адреса: from, to, cc, bcc, reply_to. Значение list_id несёт идентификатор рассылки, а не адрес человека
      - `address` string, required
      - `name` string, required: Имя отправителя или получателя, если оно было в конверте
      - `position` integer, required: Порядок адреса в своей группе
    - `snippet` string, required: Короткий пересказ письма для списка
    - `body_text` string
    - `body_html` string
    - `size_bytes` integer, required
    - `direction` 'inbound' | 'outbound', required
    - `is_read` boolean, required
    - `is_flagged` boolean, required
    - `is_answered` boolean, required
    - `is_draft` boolean, required
    - `has_attachments` boolean, required
    - `spam_verdict` 'unknown' | 'spam' | 'ham', required: Вердикт по спаму; unknown — состояние по умолчанию. Вердикт справочный и с папкой не связан: письмо во «Входящих» может нести spam от провайдера (флаг $Junk на сервере почты), а папку «Спам» задаёт только перенос. Решение человека (spam_source=user) сильнее флага сервера и правил.
    - `spam_source` 'provider' | 'rule' | 'user' | 'agent': Кто вынес вердикт. Решение человека сильнее флага сервера и правил
    - `spam_reason` string
    - `delivery` MailDeliveryState
      - `status` 'queued' | 'sending' | 'sent' | 'failed' | 'cancelled', required
      - `attempts` integer, required
      - `error_code` string
      - `next_attempt_at` string, date-time: Срок ближайшей попытки у письма в очереди: время отложенной отправки или следующего повтора после сбоя
      - `scheduled` boolean: Письмо отложено человеком: попыток ещё не было, а срок первой — next_attempt_at в будущем. Экран показывает «Запланировано на …»
    - `delivery_failure` MailDeliveryFailure: Отказ доставки, пришедший на наше отправленное письмо отдельным письмом сервера (ERP-1865). Окончательный отказ сильнее задержки.
      - `severity` 'failed' | 'delayed', required: failed — не доставлено (5.x.x), delayed — доставка задерживается (4.x.x)
      - `recipient` string, required: Адрес, которому письмо не дошло
      - `status` string: Код RFC 3463 из отчёта сервера, например 5.1.1
      - `reason` 'user_unknown' | 'domain_unknown' | 'mailbox_full' | 'mailbox_disabled' | 'policy' | 'unreachable' | 'rejected' | 'delayed', required: Причина кодом; экран показывает её словами
      - `diagnostic` string: Ответ сервера получателя как есть
      - `report_message_id` string, uuid
    - `bounce_of_id` string, uuid
    - `sent_at` string, date-time, nullable, required
    - `received_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `attachments` MailAttachment[]
      - `id` string, uuid, required
      - `message_id` string, uuid, required
      - `filename` string, required
      - `content_type` string, required
      - `size_bytes` integer, required
      - `content_id` string: Заполняется у картинок, вставленных в тело письма через cid:
      - `is_inline` boolean, required: Встроенная в тело картинка, а не документ
      - `scan_status` 'pending' | 'clean' | 'infected' | 'skipped', required: Состояние антивирусной проверки файла. pending существует потому, что письмо сохраняется целиком, а проверка идёт потоком: видеть письмо можно сразу, скачать вложение — только после вердикта.
      - `created_at` string, date-time, required
  - `total` integer, required
  - `limit` integer, required
  - `offset` integer, required
  - `has_more` boolean, required

## Other responses

- `400`: Некорректный запрос или нарушение бизнес-правила
- `401`: Сессия, ключ или кабинет не подтверждены
- `403`: Текущая роль не имеет требуемого права

---

[API](https://skmtc.dev/akeda/apis/akeda-erp-client-api.md) · [All operations](https://skmtc.dev/akeda/apis/akeda-erp-client-api/llms.txt) · [OpenAPI document](https://skmtc.dev/akeda/apis/akeda-erp-client-api/revisions/3c60ded179f2?raw)