Skip to main content

Imported from docs/archive/LOCAL_MANAGED_EMAIL_MIGRATION.md. Edit source file, then re-run sync.

Local Mailcow Integration

This document is archived.

Mailcow is no longer part of Nova's supported email architecture. Nova now uses SES-managed email routes, reply addresses, and queue-backed inbound processing instead of Mailcow-hosted mailboxes.

Use the active SES-managed email integration docs for current setup guidance. The repo-level EMAIL_SYSTEM.md file remains an engineering reference, but it is not part of the published docs site.

The historical content below is preserved only for reference when reviewing old environments or migrations away from Mailcow.

Prerequisites​

  • Mailcow is running (official mailcow-dockerized stack).
  • You have a Mailcow API key with mailbox/domain management access.
  • Nova repo is available locally.

1. Configure Nova API for Mailcow​

Edit api/.env:

MAILCOW_ENABLED=true
MAILCOW_API_URL=http://<mailcow-host>
MAILCOW_API_KEY=<mailcow-api-key>
MAILCOW_DOMAIN=agents.nova.local
MAILCOW_SMTP_HOST=<mailcow-smtp-host>
MAILCOW_SMTP_PORT=587
MAILCOW_SMTP_SECURE=false
MAILCOW_IMAP_HOST=<mailcow-imap-host>
MAILCOW_IMAP_PORT=993
MAILCOW_IMAP_SECURE=true
MAILCOW_DEFAULT_QUOTA_MB=2048

2. Verify Mailcow connectivity​

From repo root:

npm run verify:mailcow

This checks:

  • Mailcow API reachability via X-API-Key
  • SMTP host/port reachability
  • IMAP host/port reachability

3. Start Nova in Mailcow mode​

npm run start:mailcow

This starts:

  • Mongo + Redis via Docker Compose
  • API (api, dev mode)
  • Dashboard (dashboard, dev mode)

4. Provision assistant mailbox from dashboard​

  1. Open http://localhost:3002/dashboard/agents/new
  2. Create assistant with Auto-provision assistant mailbox in Mailcow enabled
  3. Submit

Expected result:

  • Assistant is created
  • Managed mailbox is created in Mailcow
  • SMTP/IMAP connection is created in Nova
  • Default sender is created and attached to assistant

5. Send from provisioned identity​

  1. Go to assistant command view or Telegram flow
  2. Send instruction like: send an email to you@example.com saying hello

Expected result:

  • Action is queued/completed
  • Delivery worker sends via provisioned Mailcow SMTP credentials

Troubleshooting​

  • Mailcow provisioning is not enabled:
    • Ensure MAILCOW_ENABLED=true in api/.env
  • Mailcow failed to create mailbox:
    • Validate MAILCOW_API_URL, API key, and domain in Mailcow
  • SMTP/IMAP test failures:
    • Re-run npm run verify:mailcow
    • Confirm firewall/ports and hostnames from Nova runtime