Mail integration

Tycoonbox integrates with production mailcow at mail.21tycoons.dev (168.119.245.91) and backup MX at backupmx.21tycoons.dev (77.42.123.166).

The mail repo (~/21tycoons/mail) extends this API with delivery webhooks on the same /api/v1 contract.

Setup

1. Settings → Mailcow bridge — paste API key from mailcow UI (docs/ops/mailcow-api-key-acl.md in mail repo)
2. Settings → Route53 auto-DNS (optional) — AWS credentials + hosted zone ID; upserts MX/SPF/DKIM/DMARC on provision
3. Settings → Public panel URL — required for mail delivery webhooks (e.g. https://panel.21tycoons.com)
4. Mail → Add domain — provisions domain on mailcow, syncs DNS, registers webhooks
5. Create mailbox — link to an app for automatic SMTP env injection

App deploy integration

When a mailbox is linked to an app, deploys inject:

Rails apps can use standard Action Mailer SMTP config — see mail/docs/integrations/rails-action-mailer.md.

Mail repo ops

Verify DNS and health from the mail repo:

cd ~/21tycoons/mail
npm run ops:mailcow:dns-check -- customer.com
npm run ops:mailcow:health
npm run ops:backup-mx:health

Route53 auto-DNS

When AWS credentials are configured, Maildomains::DnsProvisioner upserts:

Hosted zone is resolved from the default zone ID or by walking domain labels (customer.com, parent zones).

Delivery webhooks

On domain provision, Tycoonbox registers delivery, bounce, and failure webhooks (skipped on stock mailcow until the mail repo API is the endpoint).

Endpoint: POST /webhooks/mailbird/:domain_id/:token

Verification: X-Mailbird-Timestamp + X-Mailbird-Signature headers (HMAC-SHA256 of timestamp.body).

Events appear in the dashboard activity feed and link to the sending mailbox when from matches.

App server outbound relay

When a server is provisioned or bootstrapped, its public IPv4 is registered as a mailcow forwarding host (POST /add/fwdhost). Apps on that server can relay outbound mail through mailcow without per-message SMTP auth (mailbox SMTP on :587 still works for panel deploys).

Architecture

Tycoonbox panel
  → Mailcow::Client (Faraday)
  → mail.21tycoons.dev/api/v1
  → Postfix/Dovecot/Rspamd on Hetzner
  ← delivery webhooks

Route53 (optional)
  ← DnsProvisioner upserts MX/SPF/DKIM/DMARC

Customer app
  → SMTP submission :587
  → mailcow authenticates mailbox
  → or relay from registered server IP (fwdhost)