Email API

Подключите почтовый ящик, и ассистент будет создавать или автоматически отправлять обоснованные ответы, управляемые порогом уверенности. Ранний доступ.

На этой странице

Ранний доступ / предпросмотр. Email API доступен партнёрам по разработке. Поля и эндпоинты могут измениться до общего релиза.

Email API подключается напрямую к почтовому ящику — Gmail, Outlook или любой аккаунт IMAP/SMTP — читает входящие сообщения и создаёт обоснованные черновики ответов на основе ваших знаний. Каждый ответ несёт оценку уверенности (confidence). Вы задаёте порог автоотправки для каждого ящика: ответы на пороге или выше отправляются автоматически, менее уверенные сохраняются как черновик для проверки человеком. Использует базовый URL, Bearer-аутентификацию и формат ошибок из обзора API.

https://api.praktickai.app/v1/email

Как это работает

1. Один раз подключите почтовый ящик через OAuth (Gmail/Outlook) или учётные данные IMAP.
2. Приходит входящее письмо; мы уведомляем ваш сервер вебхуком email.inbound.
3. Вы (или наш автоматический конвейер) запрашиваете черновик — обоснованный ответ с оценкой уверенности.
4. Если уверенность ≥ порога autosend_threshold ящика, ответ отправляется автоматически; иначе сохраняется как черновик.

Начните с высокого порога (например, 0,9), чтобы почти всё проверял человек, и снижайте его по мере роста доверия к черновикам.

Подключение почтового ящика

POST /v1/email/mailboxes/

Подключите ящик, из которого ассистент будет читать и отвечать от вашего имени. Для Gmail и Outlook передайте `provider` и завершите возвращённый OAuth `authorization_url`; для других серверов передайте настройки IMAP/SMTP. Ящик хранит политику автоотправки.

Параметр	Тип	Обязательный	Описание
provider	string	да	Одно из `gmail`, `outlook` или `imap`.
address	string	да	Адрес ящика, например `support@acme.com`.
autosend_threshold	number	нет	Уверенность (0–1), на которой или выше ответы отправляются автоматически. По умолчанию `1.0` (никогда автоматически — всегда черновик).
imap	object	условно	Обязательно, когда `provider` равен `imap`: `{ host, port, username, password }` для чтения.
smtp	object	условно	Обязательно, когда `provider` равен `imap`: `{ host, port, username, password }` для отправки.

curl https://api.praktickai.app/v1/email/mailboxes/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gmail",
    "address": "support@acme.com",
    "autosend_threshold": 0.9
  }'

{
  "id": "mbx_a1b2c3",
  "provider": "gmail",
  "address": "support@acme.com",
  "status": "pending_authorization",
  "autosend_threshold": 0.9,
  "authorization_url": "https://admin.praktickai.app/oauth/gmail?state=mbx_a1b2c3",
  "created_at": "2026-07-16T09:12:00Z"
}

Поле	Тип	Описание
id	string	Идентификатор ящика с префиксом `mbx_`.
status	string	`pending_authorization`, `active` или `error`.
autosend_threshold	number	Уверенность, на которой или выше ответы отправляются автоматически.
authorization_url	string	Присутствует для OAuth-провайдеров, пока ящик не авторизован. Откройте один раз, чтобы предоставить доступ.

Предоставляйте только нужные разрешения. Для автоматизации ответов достаточно чтения и отправки; ассистент никогда не удаляет письма. Отозвать доступ можно в любой момент в консоли администратора.

GET /v1/email/mailboxes/

Возвращает подключённые ящики и их текущую политику автоотправки.

{
  "data": [
    {
      "id": "mbx_a1b2c3",
      "address": "support@acme.com",
      "provider": "gmail",
      "status": "active",
      "autosend_threshold": 0.9
    }
  ]
}

Создание черновика ответа

POST /v1/email/draft/

Создаёт обоснованный черновик ответа на входящее сообщение. Ответ включает текст черновика, источники, на которые он опирался, и оценку `confidence` от 0 до 1. Если `confidence` на пороге `autosend_threshold` ящика или выше, ответ отправляется и `action` равно `sent`; иначе он сохраняется и `action` равно `drafted`.

Параметр	Тип	Обязательный	Описание
mailbox_id	string	да	Ящик, для которого создаётся ответ.
message_id	string	условно	Id входящего сообщения для ответа. Укажите это или `email`.
email	object	условно	Сырое входящее письмо `{ from, subject, body }`, если сообщение у нас не сохранено.
instructions	string	нет	Доп. указания по тону или правилам, например "кратко, предложи звонок".

curl https://api.praktickai.app/v1/email/draft/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_a1b2c3",
    "message_id": "msg_7788",
    "instructions": "Дружелюбно, сначала предложи инструкцию для самообслуживания."
  }'

{
  "id": "drf_44aa",
  "mailbox_id": "mbx_a1b2c3",
  "in_reply_to": "msg_7788",
  "subject": "Re: Сброс пароля",
  "body": "Здравствуйте, Яна! Пароль можно сбросить на экране входа через 'Забыли пароль'. Вот пошаговая инструкция...",
  "confidence": 0.94,
  "action": "sent",
  "sources": [
    { "title": "Сброс пароля", "url": "https://help.acme.com/reset", "source_id": "src_notion_01" }
  ],
  "created_at": "2026-07-16T09:20:11Z"
}

Поле	Тип	Описание
id	string	Идентификатор черновика с префиксом `drf_`.
body	string	Сгенерированный текст ответа.
confidence	number	Уверенность модели в ответе, от 0 до 1.
action	string	`sent`, если уверенность ≥ порога и ответ отправлен, иначе `drafted`.
sources	array	Фрагменты знаний, на которых основан ответ — каждый с `title`, `url` и `source_id`.
in_reply_to	string	Id входящего сообщения, на которое отвечает ответ.

Когда `action` равно `drafted`, ответ ждёт в ящике проверки человеком — ничего не отправлено. Только `action: sent` означает, что клиент получил письмо.

Отправка письма

POST /v1/email/send/

Отправляет сообщение из подключённого ящика. Используйте для отправки проверенного черновика (передайте `draft_id`) или для произвольного письма (передайте `to`, `subject`, `body`).

Параметр	Тип	Обязательный	Описание
mailbox_id	string	да	Ящик, из которого идёт отправка.
draft_id	string	условно	Отправить ранее созданный черновик как есть или после правок.
to	string	условно	Адрес получателя для произвольного письма.
subject	string	условно	Тема произвольного письма.
body	string	условно	Тело произвольного письма или отредактированного черновика.

curl https://api.praktickai.app/v1/email/send/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "mailbox_id": "mbx_a1b2c3",
    "draft_id": "drf_44aa"
  }'

{
  "id": "msg_9001",
  "mailbox_id": "mbx_a1b2c3",
  "direction": "outbound",
  "status": "sent",
  "to": "jana@example.com",
  "subject": "Re: Сброс пароля",
  "created_at": "2026-07-16T09:21:03Z"
}

Получение сообщения

GET /v1/email/messages/{id}/

Возвращает одно входящее или исходящее сообщение по id, включая тело и связанный черновик, если он есть.

curl https://api.praktickai.app/v1/email/messages/msg_7788/ \
  -H "Authorization: Bearer pk_live_xxxxxxxxxxxxxxxx"

{
  "id": "msg_7788",
  "mailbox_id": "mbx_a1b2c3",
  "direction": "inbound",
  "from": "jana@example.com",
  "subject": "Сброс пароля",
  "body": "Здравствуйте, не могу войти, письмо для сброса не приходит.",
  "received_at": "2026-07-16T09:18:44Z"
}

Вебхуки

Зарегистрируйте endpoint вебхука в консоли администратора, чтобы реагировать на почтовые события. Каждая доставка подписана; проверьте заголовок `PraktickAI-Signature` по своему секрету подписи, прежде чем доверять данным.

Событие	Срабатывает, когда
email.inbound	В подключённый ящик приходит новое сообщение.
email.draft_created	Создан обоснованный черновик (ниже порога автоотправки).
email.outbound	Отправлен ответ — автоматически или после проверки.

{
  "type": "email.inbound",
  "created_at": "2026-07-16T09:18:45Z",
  "data": {
    "message_id": "msg_7788",
    "mailbox_id": "mbx_a1b2c3",
    "from": "jana@example.com",
    "subject": "Сброс пароля"
  }
}

Быстро возвращайте из вебхука статус 2xx. Неуспешные доставки мы повторяем с экспоненциальной задержкой до 24 часов.