Novij Mail Service

Novij Mail Service ставится как отдельный backend с API и worker. Он подключает проектные IMAP/SMTP ящики, забирает новые письма, сохраняет metadata и вложения, а затем отправляет события в Actions или webhook проекта.

Novij Mail Service runs as a standalone backend with API and worker processes. It connects project IMAP/SMTP mailboxes, fetches new messages, stores metadata and attachments, and dispatches events to Actions or a project webhook.

Инсталлятор проверяет Ubuntu 24.04, DNS, nginx, PostgreSQL, systemd units, TLS и локальный smoke. Для production секреты передаются через env/CI variables, не через git.

The installer validates Ubuntu 24.04, DNS, nginx, PostgreSQL, systemd units, TLS, and a local smoke check. Production secrets are provided through env/CI variables, not through git.

curl -fsSL https://packages.novij.tech/services/mail/install.sh | sudo bash -s -- install konan-mail.novij.tech
curl -fsS https://konan-mail.novij.tech/api/v1/health
curl -fsS https://konan-mail.novij.tech/.well-known/novij/status.json
novij-mailctl registry status --once

Для стандартного flow укажите project_id и Actions service id. После этого входящие письма будут уходить в Actions как service events.

For the standard flow, provide project_id and the Actions service id. Inbound messages will then be dispatched to Actions as service events.

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/event-targets \
  -H 'content-type: application/json' \
  -d '{
    "project_id": "project_demo",
    "type": "actions_service",
    "actions_service_id": "novij.actions"
  }'

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/event-targets/TARGET_ID/test

Mailbox API хранит IMAP/SMTP настройки и зашифрованный пароль. В примере пароль показан как placeholder; реальные значения передавайте только через защищённый runtime.

The mailbox API stores IMAP/SMTP settings and an encrypted password. The example uses a placeholder password; pass real values only through a protected runtime.

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/mailboxes \
  -H 'content-type: application/json' \
  -d '{
    "project_id": "project_demo",
    "owner_wallet_id": "wallet_demo",
    "display_name": "Invoices inbox",
    "email": "inbox@example.com",
    "provider": "custom",
    "incoming": {"protocol": "imap", "host": "imap.example.com", "port": 993, "tls": "required"},
    "outgoing": {"protocol": "smtp", "host": "smtp.example.com", "port": 587, "tls": "starttls"},
    "auth": {"type": "password", "username": "inbox@example.com", "password": "APP_PASSWORD"},
    "folders": ["INBOX"],
    "idempotency_key": "mailbox-project-demo-invoices"
  }'

После подключения можно проверить credentials, принудительно синхронизировать папку и скачать сохранённое вложение по attachment id.

After connecting a mailbox, validate credentials, force a folder sync, and download a stored attachment by attachment id.

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/mailboxes/MAILBOX_ID/test
curl -fsS -X POST https://konan-mail.novij.tech/api/v1/mailboxes/MAILBOX_ID/sync-now
curl -fsS https://konan-mail.novij.tech/api/v1/attachments/ATTACHMENT_ID/download -o attachment.bin

Backfill сканирует IMAP за период, применяет generic фильтры письма и вложений, а затем в обычном режиме создаёт те же события, что и live sync.

Backfill scans IMAP for a period, applies generic message and attachment filters, and in normal mode creates the same events as live sync.

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/mailboxes/MAILBOX_ID/backfill \
  -H 'content-type: application/json' \
  -d '{
    "from_date": "2026-01-01",
    "to_date": "2026-07-05",
    "filters": {
      "from": ["billing@example.com"],
      "subject_contains": ["счет"],
      "has_attachments": true,
      "attachment_name_regex": "\\.pdf$",
      "attachment_mime": ["application/pdf"]
    },
    "dispatch": {"target": "actions", "mode": "normal_events"},
    "dry_run": true
  }'

novij-mailctl mailbox backfill MAILBOX_ID \
  --from 2026-01-01 \
  --to 2026-07-05 \
  --filter-json '{"subject_contains":["счет"],"has_attachments":true,"attachment_name_regex":"\\.pdf$"}' \
  --dispatch-target actions \
  --dry-run

Минимальный send API кладёт письмо в очередь worker. Статус отправки читается отдельным GET-запросом.

The minimal send API queues a message for the worker. Send status is read through a separate GET request.

curl -fsS -X POST https://konan-mail.novij.tech/api/v1/send \
  -H 'content-type: application/json' \
  -d '{
    "project_id": "project_demo",
    "mailbox_id": "MAILBOX_ID",
    "from": {"email": "inbox@example.com"},
    "to": [{"email": "recipient@example.com"}],
    "subject": "Novij Mail Service test",
    "text": "Hello from Novij Mail Service",
    "idempotency_key": "send-project-demo-001"
  }'

curl -fsS https://konan-mail.novij.tech/api/v1/send/SEND_ID

curl -fsS https://konan-mail.novij.tech/api/v1/version
curl -fsS https://konan-mail.novij.tech/api/v1/settings
curl -fsS https://konan-mail.novij.tech/.well-known/novij/service-health
curl -fsS https://konan-mail.novij.tech/api/v1/service-registry/status
curl -fsSL https://packages.novij.tech/services/mail/install.sh | sudo bash -s -- update
curl -fsSL https://packages.novij.tech/services/mail/install.sh | sudo bash -s -- rollback