Skip to main content

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

Local Mailcow Integration

This guide enables full managed-mailbox flow locally:

  1. Nova provisions assistant mailboxes in Mailcow.
  2. Nova sends outbound email from provisioned assistant identities.
  3. Nova can validate SMTP/IMAP endpoints for those connections.

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