---
title: "Email AI-CRM API"
description: "Адмінські маршрути email CRM (канали + sourceChannel), процесор cron, примітка про очистку токенів, і вхідний webhook"
locale: "uk"
---
# Email AI-CRM API

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

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

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

Відправка чернеток використовує `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": "", "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": "" }`

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-сервіс).

**Приклад:**

```bash
curl -X POST "$BASE_URL/api/cron/email-processor" \
  -H "Authorization: Bearer $CRON_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"poll"}'
```

### `GET /api/cron/email-analytics`

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

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

`GET/POST /api/cron/cleanup-email-tokens` — видаляє прострочені `email_login_tokens`. Той самий pattern з `CRON_SECRET`. Документація — [Ring Mailer](/docs/features/ring-mailer.md); не відноситься до 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):**

```json
{
  "messageId": "",
  "from": "sender@example.com",
  "fromName": "НЕОБОВ’ЯЗКОВО",
  "to": "info@example.com",
  "subject": "Тема листа",
  "bodyText": "Текст листа",
  "bodyHtml": "опційно",
  "date": "2026-06-10T12:00:00.000Z",
  "inReplyTo": "",
  "references": ["", ""]
}
```

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

---

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

  
- [features/email-ai-crm](/docs/features/email-ai-crm.md) — Передумова: налаштування операторів, секрети каналів, різниця Auth та CRM SMTP.

  
- [architecture/email-ai-crm](/docs/architecture/email-ai-crm.md) — Деталі реалізації: EmailProcessor та jsonb-collection persist.

  
- [examples/email-ai-crm](/docs/examples/email-ai-crm.md) — Workflow: локальний poll + відправка чернетки (smoke test).

  
- [features/ring-mailer](/docs/features/ring-mailer.md) — Див. також: cron очистки токенів авторизації, SMTP_* plane.

  
- [features/owner-project-lab](/docs/features/owner-project-lab.md) — Див. також: адмінський shell замовлень CRM.