Почта через API

Канал «Почта» работает с ящиком компании по IMAP и SMTP — как почтовая программа. Новые письма приходят уведомлениями, а методы ящика дают всё остальное: папки, поиск, письмо целиком, флаги, перенос, ответы в цепочку, пересылку и черновики. Общие методы — sendMessage, история, контакты — работают и у почты.

Все методы почты — POST с телом JSON, адрес как у остальных методов: https://api.gratio.net/waInstance{idInstance}/{метод}/{apiTokenInstance}. У каналов MAX, Telegram и WhatsApp методы почты отвечают 501.

Подключить ящик — в кабинете, см. Почта, или из своего приложения методом connectMailbox.

Чат и цепочка

• chatId — адрес собеседника в нижнем регистре, домен — юникодом: "info@пример.рф". Входящее письмо попадает в чат адреса из Reply-To, а без него — отправителя. Своё письмо — в чат первого получателя.
• Свои адреса — адрес ящика и адреса из настройки emailAliases. Письма с них считаются своими, см. Настройки ящика.
• threadId — idMessage первого письма цепочки. В чате бывает несколько цепочек, а в цепочке — несколько адресатов.
• chatId у почты — только адрес. Номер телефона 79991234567@c.us у почты не работает.

Три письма — один чат и две цепочки:

Мария → «Запись на пробное»          чат maria@client.ru, цепочка c62b…
Школа → «Re: Запись на пробное»      тот же чат, та же цепочка
Мария → «Вопрос по оплате»           тот же чат, новая цепочка

Как указать письмо

Методы, которые работают с одним письмом, принимают его одним из способов:

• idMessage — 20 hex-знаков от Message-ID. Он одинаков у письма в любой папке: копия вашего письма в «Отправленных» имеет тот же idMessage, что вернула отправка.
• По messageId Gratio ищет письмо в папке folder, если она задана, затем во «Входящих», «Отправленных», «Архиве», «Вся почта», «Черновиках», «Спаме» и «Корзине».
• uid меняется, когда письмо переносят в другую папку: новый номер — в ответе moveMessages. Если у папки сменился uidValidity, старые uid этой папки больше не действуют — перечитайте её.
• Письма нет — 400 not_found.

Несколько писем

markMessages, setMessageFlags, moveMessages, copyMessages и deleteMessages принимают до 500 писем:

Одно письмо можно указать и как в остальных методах: folder + uid, idMessage или messageId.

Как указать папку

Папку в полях folder, to и parent указывают ролью, именем на сервере или названием:

Роль Gratio определяет по флагам папок (SPECIAL-USE), без них — по привычным именам: Sent, «Отправленные», Trash, «Корзина». Какие роли нашлись в ящике — в getMailboxInfo, все папки — в getFolders. Папки нет — 400 folder_not_found.

Конверт письма

Конверт — письмо без тела: где лежит, от кого, кому, тема, флаги. Его возвращают getMessages, searchMessages и getThread, а getEmail — конверт вместе с телом.

Письмо Марии во «Входящих»:

{
  "idMessage": "c62b698304229a98aad3",
  "folder": "INBOX",
  "uid": 1532,
  "uidValidity": 1700000000,
  "chatId": "maria@client.ru",
  "messageId": "CAF1xQm7v2k@mail.gmail.com",
  "threadId": "c62b698304229a98aad3",
  "inReplyTo": null,
  "references": [],
  "timestamp": 1791823658,
  "internalDate": 1791823661,
  "from": {"address": "maria@client.ru", "name": "Мария"},
  "to": [{"address": "info@school.ru", "name": ""}],
  "cc": [],
  "replyTo": [],
  "subject": "Запись на пробное",
  "flags": ["\\Seen"],
  "seen": true,
  "flagged": false,
  "answered": false,
  "draft": false,
  "size": 4821,
  "hasAttachments": false
}

В JSON обратная косая черта удваивается: флаг \Seen записывается как "\\Seen".

Общие методы у почты

Пределы

Сутки считаются по UTC. Сколько писем ушло сегодня — sentToday в getMailboxInfo.

Что Gratio меняет в ящике

Gratio читает письма, не помечая их прочитанными. Ящик меняется только по вашим вызовам: флаги, перенос, удаление, папки, черновики. Отправка меняет ещё две вещи: копия письма ложится в «Отправленные», если сервер не кладёт её сам, а письмо, на которое ответили через replyEmail, помечается «отвечено». Все изменения сразу видны сотрудникам в их почтовых программах.

Что дальше

• connectMailbox — подключить ящик из своего приложения.
• getMessages — письма папки страницами.
• sendEmail — письмо со всеми полями.
• Письмо — уведомление о новом письме.