Email AI-CRM API

Доступ адміністратора

Всі маршрути /api/admin/email/* потребують аутентифікованої сесії platform admin (роль admin або superadmin).

Адмін-інтерфейс

Інтерфейс перегляду знаходиться за адресою /admin/crm/* (CrmAdminShell). API залишаються /api/admin/email/* — див. Email AI-CRM.

Cron / webhook

/api/cron/* та /api/webhooks/email/inbound використовують CRON_SECRET або WEBHOOK_EMAIL_SECRET — не user session. Якщо секрет відсутній — запит відхиляється.

CRM SMTP ≠ Auth SMTP

Відправка чернеток використовує EmailSenderService + канальний SMTP (CRM_CHANNEL_*). Для авторизаційних OTP використовується lib/mailer.ts / SMTP_*. Не плутайте це в технічній документації.

Адмін — канали

`GET /api/admin/email/channels`

Тільки для читання: статус каналів CRM (без паролей). Використовується для фільтрації inbox за каналами в UI.

Відповідь:

json


{
  "channels": [
    {
      "id": "primary",
      "name": "Primary",
      "flow": "standard",
      "mailbox": "INBOX",
      "imapHost": "mail.ringdom.org",
      "imapUser": "info@ringdom.org",
      "smtpHost": "mail.ringdom.org",
      "smtpUser": "info@ringdom.org",
      "hasImapPassword": true,
      "hasSmtpPassword": true
    }
  ],
  "validation": { "ok": true, "errors": [] }
}

Реалізація: loadCrmChannels() + validateCrmChannels() з features/email-crm/pipeline/imap/config.ts.

Адмін — треди

`GET /api/admin/email/threads`

Список email-тредів.

Query	Тип	Опис
`status`	string	Фільтр: `new`, `ongoing`, `waiting`, `resolved` або всі
`sourceChannel`	string	Фільтрація за id чи назвою каналу (для мультискринькової підтримки)

Відповідь: { threads: EmailThreadRecord[] }

`PATCH /api/admin/email/threads`

Оновлення статусу треду.

Body: { "id": "<threadId>", "status": "resolved" }

`GET /api/admin/email/threads/[id]`

Детальна інформація про тред: повідомлення, чернетки, відкриті задачі.

Відповідь: { thread, messages, drafts, tasks }

Адмін — чернетки

`GET /api/admin/email/drafts`

Чернетки до відправки (status: pending), найновіші першими.

`POST /api/admin/email/drafts/[id]/approve`

Затвердити чернетку до відправки (відмітка reviewer — user із сесії).

`POST /api/admin/email/drafts/[id]/reject`

Body: { "reason": "текстове пояснення (необов'язково)" }

`POST /api/admin/email/drafts/[id]/send`

Відправити затверджену чернетку через CRM SMTP-канал (EmailSenderService).

Body (опціонально): { "toEmail": "...", "subject": "..." } — за замовчуванням з треду.

Відповідь: { "success": true, "messageId": "<smtp-message-id>" }

Email зберігається у email_messages + статус треду змінюється на waiting.

Адмін — контакти

`GET /api/admin/email/contacts`

Query	Опис
`email`, `name`, `company`, `type`	Параметри для пошуку

`POST /api/admin/email/contacts`

Body: { "email": "обовʼязково", "name?", "company?", "type?" }

Адмін — задачі

`GET /api/admin/email/tasks`

Query	Опис
`status`	`open`, `in_progress`, `overdue`, `completed` і т.д.

`POST /api/admin/email/tasks`

Body: { "threadId", "title", "taskType", ... } — приклад див. у TaskCreateInput (task-service.ts).

`POST /api/admin/email/tasks/[id]/complete`

Body: { "completionNotes?": "text" }

Адмін — аналітика

`GET /api/admin/email/analytics`

Query	Значення
`range`	`7d` (за замовчуванням), `30d`, `90d`

Відповідь: розподіл намірів/емоцій, costStats з email_api_usage, dailyStats, підсумки по чернетках/задачах.

Cron — email processor

`POST` або `GET` `/api/cron/email-processor`

Auth: Authorization: Bearer $CRON_SECRET (обовʼязково)

Body або query action:

Action	Опис
`poll` (default)	`pollInboundBatch()` — забрати UNSEEN по каналах, обробити, закрити зʼєднання
`status`	Статистика процесора + IMAP (`getEmailProcessor()` для цієї дії)
`stop`	Зупинити IDLE listener
`start`	Старт IDLE (потрібен `EMAIL_PROCESSOR_ALLOW_HTTP_START=true`)
`mark-overdue-tasks`	Виклик `EmailTaskService.processOverdueTasks()`

Екземпляри процесора створюються окремо для кожної дії (не long-running-сервіс).

Приклад:

`GET /api/cron/email-analytics`

Повертає 7-денний знімок дашборду (як admin analytics). Тільки cron-авторизація.

Очищення токенів авторизації (пов'язано)

GET/POST /api/cron/cleanup-email-tokens — видаляє прострочені email_login_tokens. Той самий pattern з CRON_SECRET. Документація — Ring Mailer; не відноситься до Email CRM напряму.

Webhook — вхідна пошта

`POST /api/webhooks/email/inbound`

Auth: Authorization: Bearer $WEBHOOK_EMAIL_SECRET або HMAC-SHA256 hex у X-Email-Webhook-Signature по raw body.

Body (JSON):

Викликає EmailProcessor.ingestEvent() з uid: 0 (без позначки IMAP як прочитаного).

Пов'язані документи

Email AI-CRM API

Доступ адміністратора

Всі маршрути /api/admin/email/* потребують аутентифікованої сесії platform admin (роль admin або superadmin).

Адмін-інтерфейс

Інтерфейс перегляду знаходиться за адресою /admin/crm/* (CrmAdminShell). API залишаються /api/admin/email/* — див. Email AI-CRM.

Cron / webhook

CRM SMTP ≠ Auth SMTP

Адмін — канали

`GET /api/admin/email/channels`

Тільки для читання: статус каналів CRM (без паролей). Використовується для фільтрації inbox за каналами в UI.

Відповідь:

json


{
  "channels": [
    {
      "id": "primary",
      "name": "Primary",
      "flow": "standard",
      "mailbox": "INBOX",
      "imapHost": "mail.ringdom.org",
      "imapUser": "info@ringdom.org",
      "smtpHost": "mail.ringdom.org",
      "smtpUser": "info@ringdom.org",
      "hasImapPassword": true,
      "hasSmtpPassword": true
    }
  ],
  "validation": { "ok": true, "errors": [] }
}

Реалізація: loadCrmChannels() + validateCrmChannels() з features/email-crm/pipeline/imap/config.ts.

Адмін — треди

`GET /api/admin/email/threads`

Список email-тредів.

Query	Тип	Опис
`status`	string	Фільтр: `new`, `ongoing`, `waiting`, `resolved` або всі
`sourceChannel`	string	Фільтрація за id чи назвою каналу (для мультискринькової підтримки)

Відповідь: { threads: EmailThreadRecord[] }

`PATCH /api/admin/email/threads`

Оновлення статусу треду.

Body: { "id": "<threadId>", "status": "resolved" }

`GET /api/admin/email/threads/[id]`

Детальна інформація про тред: повідомлення, чернетки, відкриті задачі.

Відповідь: { thread, messages, drafts, tasks }

Адмін — чернетки

`GET /api/admin/email/drafts`

Чернетки до відправки (status: pending), найновіші першими.

`POST /api/admin/email/drafts/[id]/approve`

Затвердити чернетку до відправки (відмітка reviewer — user із сесії).

`POST /api/admin/email/drafts/[id]/reject`

Body: { "reason": "текстове пояснення (необов'язково)" }

`POST /api/admin/email/drafts/[id]/send`

Відправити затверджену чернетку через CRM SMTP-канал (EmailSenderService).

Body (опціонально): { "toEmail": "...", "subject": "..." } — за замовчуванням з треду.

Відповідь: { "success": true, "messageId": "<smtp-message-id>" }

Email зберігається у email_messages + статус треду змінюється на waiting.

Адмін — контакти

`GET /api/admin/email/contacts`

Query	Опис
`email`, `name`, `company`, `type`	Параметри для пошуку

`POST /api/admin/email/contacts`

Body: { "email": "обовʼязково", "name?", "company?", "type?" }

Адмін — задачі

`GET /api/admin/email/tasks`

Query	Опис
`status`	`open`, `in_progress`, `overdue`, `completed` і т.д.

`POST /api/admin/email/tasks`

Body: { "threadId", "title", "taskType", ... } — приклад див. у TaskCreateInput (task-service.ts).

`POST /api/admin/email/tasks/[id]/complete`

Body: { "completionNotes?": "text" }

Адмін — аналітика

`GET /api/admin/email/analytics`

Query	Значення
`range`	`7d` (за замовчуванням), `30d`, `90d`

Відповідь: розподіл намірів/емоцій, costStats з email_api_usage, dailyStats, підсумки по чернетках/задачах.

Cron — email processor

`POST` або `GET` `/api/cron/email-processor`

Auth: Authorization: Bearer $CRON_SECRET (обовʼязково)

Body або query action:

Action	Опис
`poll` (default)	`pollInboundBatch()` — забрати UNSEEN по каналах, обробити, закрити зʼєднання
`status`	Статистика процесора + IMAP (`getEmailProcessor()` для цієї дії)
`stop`	Зупинити IDLE listener
`start`	Старт IDLE (потрібен `EMAIL_PROCESSOR_ALLOW_HTTP_START=true`)
`mark-overdue-tasks`	Виклик `EmailTaskService.processOverdueTasks()`

Екземпляри процесора створюються окремо для кожної дії (не long-running-сервіс).

Приклад:

`GET /api/cron/email-analytics`

Повертає 7-денний знімок дашборду (як admin analytics). Тільки cron-авторизація.

Очищення токенів авторизації (пов'язано)

Webhook — вхідна пошта

`POST /api/webhooks/email/inbound`

Auth: Authorization: Bearer $WEBHOOK_EMAIL_SECRET або HMAC-SHA256 hex у X-Email-Webhook-Signature по raw body.

Body (JSON):

Викликає EmailProcessor.ingestEvent() з uid: 0 (без позначки IMAP як прочитаного).

Пов'язані документи

Email AI-CRM API

Доступ адміністратора

Всі маршрути /api/admin/email/* потребують аутентифікованої сесії platform admin (роль admin або superadmin).

Адмін-інтерфейс

Інтерфейс перегляду знаходиться за адресою /admin/crm/* (CrmAdminShell). API залишаються /api/admin/email/* — див. Email AI-CRM.

Cron / webhook

CRM SMTP ≠ Auth SMTP

Адмін — канали

`GET /api/admin/email/channels`

Тільки для читання: статус каналів CRM (без паролей). Використовується для фільтрації inbox за каналами в UI.

Відповідь:

json


{
  "channels": [
    {
      "id": "primary",
      "name": "Primary",
      "flow": "standard",
      "mailbox": "INBOX",
      "imapHost": "mail.ringdom.org",
      "imapUser": "info@ringdom.org",
      "smtpHost": "mail.ringdom.org",
      "smtpUser": "info@ringdom.org",
      "hasImapPassword": true,
      "hasSmtpPassword": true
    }
  ],
  "validation": { "ok": true, "errors": [] }
}

Реалізація: loadCrmChannels() + validateCrmChannels() з features/email-crm/pipeline/imap/config.ts.

Адмін — треди

`GET /api/admin/email/threads`

Список email-тредів.

Query	Тип	Опис
`status`	string	Фільтр: `new`, `ongoing`, `waiting`, `resolved` або всі
`sourceChannel`	string	Фільтрація за id чи назвою каналу (для мультискринькової підтримки)

Відповідь: { threads: EmailThreadRecord[] }

`PATCH /api/admin/email/threads`

Оновлення статусу треду.

Body: { "id": "<threadId>", "status": "resolved" }

`GET /api/admin/email/threads/[id]`

Детальна інформація про тред: повідомлення, чернетки, відкриті задачі.

Відповідь: { thread, messages, drafts, tasks }

Адмін — чернетки

`GET /api/admin/email/drafts`

Чернетки до відправки (status: pending), найновіші першими.

`POST /api/admin/email/drafts/[id]/approve`

Затвердити чернетку до відправки (відмітка reviewer — user із сесії).

`POST /api/admin/email/drafts/[id]/reject`

Body: { "reason": "текстове пояснення (необов'язково)" }

`POST /api/admin/email/drafts/[id]/send`

Відправити затверджену чернетку через CRM SMTP-канал (EmailSenderService).

Body (опціонально): { "toEmail": "...", "subject": "..." } — за замовчуванням з треду.

Відповідь: { "success": true, "messageId": "<smtp-message-id>" }

Email зберігається у email_messages + статус треду змінюється на waiting.

Адмін — контакти

`GET /api/admin/email/contacts`

Query	Опис
`email`, `name`, `company`, `type`	Параметри для пошуку

`POST /api/admin/email/contacts`

Body: { "email": "обовʼязково", "name?", "company?", "type?" }

Адмін — задачі

`GET /api/admin/email/tasks`

Query	Опис
`status`	`open`, `in_progress`, `overdue`, `completed` і т.д.

`POST /api/admin/email/tasks`

Body: { "threadId", "title", "taskType", ... } — приклад див. у TaskCreateInput (task-service.ts).

`POST /api/admin/email/tasks/[id]/complete`

Body: { "completionNotes?": "text" }

Адмін — аналітика

`GET /api/admin/email/analytics`

Query	Значення
`range`	`7d` (за замовчуванням), `30d`, `90d`

Відповідь: розподіл намірів/емоцій, costStats з email_api_usage, dailyStats, підсумки по чернетках/задачах.

Cron — email processor

`POST` або `GET` `/api/cron/email-processor`

Auth: Authorization: Bearer $CRON_SECRET (обовʼязково)

Body або query action:

Action	Опис
`poll` (default)	`pollInboundBatch()` — забрати UNSEEN по каналах, обробити, закрити зʼєднання
`status`	Статистика процесора + IMAP (`getEmailProcessor()` для цієї дії)
`stop`	Зупинити IDLE listener
`start`	Старт IDLE (потрібен `EMAIL_PROCESSOR_ALLOW_HTTP_START=true`)
`mark-overdue-tasks`	Виклик `EmailTaskService.processOverdueTasks()`

Екземпляри процесора створюються окремо для кожної дії (не long-running-сервіс).

Приклад:

`GET /api/cron/email-analytics`

Повертає 7-денний знімок дашборду (як admin analytics). Тільки cron-авторизація.

Очищення токенів авторизації (пов'язано)

Webhook — вхідна пошта

`POST /api/webhooks/email/inbound`

Auth: Authorization: Bearer $WEBHOOK_EMAIL_SECRET або HMAC-SHA256 hex у X-Email-Webhook-Signature по raw body.

Body (JSON):

Викликає EmailProcessor.ingestEvent() з uid: 0 (без позначки IMAP як прочитаного).

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Documentation

Швидкий вхід (CTO · аудитори · агенти)

Loading documentation...

Loading documentation...

Loading documentation...

Email AI-CRM API

Адмін — канали

GET /api/admin/email/channels

Адмін — треди

GET /api/admin/email/threads

PATCH /api/admin/email/threads

GET /api/admin/email/threads/[id]

Адмін — чернетки

GET /api/admin/email/drafts

POST /api/admin/email/drafts/[id]/approve

POST /api/admin/email/drafts/[id]/reject

POST /api/admin/email/drafts/[id]/send

Адмін — контакти

GET /api/admin/email/contacts

POST /api/admin/email/contacts

Адмін — задачі

GET /api/admin/email/tasks

POST /api/admin/email/tasks

POST /api/admin/email/tasks/[id]/complete

Адмін — аналітика

GET /api/admin/email/analytics

Cron — email processor

POST або GET /api/cron/email-processor

GET /api/cron/email-analytics

Очищення токенів авторизації (пов'язано)

Webhook — вхідна пошта

POST /api/webhooks/email/inbound

Пов'язані документи

Related documentation

Email AI-CRM

Email AI-CRM architecture

Email AI-CRM developer guide

Ring Mailer & RingdomX Mail

Email AI-CRM API

Адмін — канали

GET /api/admin/email/channels

Адмін — треди

GET /api/admin/email/threads

PATCH /api/admin/email/threads

GET /api/admin/email/threads/[id]

Адмін — чернетки

GET /api/admin/email/drafts

POST /api/admin/email/drafts/[id]/approve

POST /api/admin/email/drafts/[id]/reject

POST /api/admin/email/drafts/[id]/send

Адмін — контакти

GET /api/admin/email/contacts

POST /api/admin/email/contacts

Адмін — задачі

GET /api/admin/email/tasks

POST /api/admin/email/tasks

POST /api/admin/email/tasks/[id]/complete

Адмін — аналітика

GET /api/admin/email/analytics

Cron — email processor

POST або GET /api/cron/email-processor

GET /api/cron/email-analytics

Очищення токенів авторизації (пов'язано)

Webhook — вхідна пошта

POST /api/webhooks/email/inbound

Пов'язані документи

Related documentation

`GET /api/admin/email/channels`

`GET /api/admin/email/threads`

`PATCH /api/admin/email/threads`

`GET /api/admin/email/threads/[id]`

`GET /api/admin/email/drafts`

`POST /api/admin/email/drafts/[id]/approve`

`POST /api/admin/email/drafts/[id]/reject`

`POST /api/admin/email/drafts/[id]/send`

`GET /api/admin/email/contacts`

`POST /api/admin/email/contacts`

`GET /api/admin/email/tasks`

`POST /api/admin/email/tasks`

`POST /api/admin/email/tasks/[id]/complete`

`GET /api/admin/email/analytics`

`POST` або `GET` `/api/cron/email-processor`

`GET /api/cron/email-analytics`

`POST /api/webhooks/email/inbound`

`GET /api/admin/email/channels`

`GET /api/admin/email/threads`

`PATCH /api/admin/email/threads`

`GET /api/admin/email/threads/[id]`

`GET /api/admin/email/drafts`

`POST /api/admin/email/drafts/[id]/approve`

`POST /api/admin/email/drafts/[id]/reject`

`POST /api/admin/email/drafts/[id]/send`

`GET /api/admin/email/contacts`

`POST /api/admin/email/contacts`

`GET /api/admin/email/tasks`

`POST /api/admin/email/tasks`

`POST /api/admin/email/tasks/[id]/complete`

`GET /api/admin/email/analytics`

`POST` або `GET` `/api/cron/email-processor`

`GET /api/cron/email-analytics`

`POST /api/webhooks/email/inbound`

`GET /api/admin/email/channels`

`GET /api/admin/email/threads`

`PATCH /api/admin/email/threads`

`GET /api/admin/email/threads/[id]`

`GET /api/admin/email/drafts`

`POST /api/admin/email/drafts/[id]/approve`

`POST /api/admin/email/drafts/[id]/reject`

`POST /api/admin/email/drafts/[id]/send`

`GET /api/admin/email/contacts`

`POST /api/admin/email/contacts`

`GET /api/admin/email/tasks`

`POST /api/admin/email/tasks`

`POST /api/admin/email/tasks/[id]/complete`

`GET /api/admin/email/analytics`

`POST` або `GET` `/api/cron/email-processor`

`GET /api/cron/email-analytics`

`POST /api/webhooks/email/inbound`