Deployment and Operations

Runtime Components

• FastAPI app (HTTP)
• SMTP inbound listener (port 25)
• Outbox worker for direct SMTP send
• Durable webhook delivery worker
• SQLite database on persistent volume (/data/zmail.db)

Fly.io Deployment

fly deploy --now
fly status --app zmail-zergai
fly checks list --app zmail-zergai
fly logs --app zmail-zergai

Required Secrets and Config

• ZMAIL_API_KEY
• DOMAIN_KEY_ENCRYPTION_SECRET (stable and backed up; changing it without re-encrypting keys disables per-domain DKIM)
• Mail domain and SMTP-related environment from config.py

DNS Requirements

At minimum for domain mail flow:

• A record for mail host to Fly IPv4
• MX record pointing to mail host
• TXT SPF record allowing mail host
• DKIM/DMARC records when enabled

See also: DNS_DELIVERABILITY.md.

Health Verification

• API check: GET /health
• SMTP check: Fly service check on TCP 25
• App surface check: GET /, GET /login, GET /admin/login

Post-Deploy Smoke Checklist

1. Open / and /login in browser.
2. Login with test user and verify /app loads.
3. GET /app/api/session with session token succeeds.
4. Create a sending domain and verify its DNS TXT record.
5. Create a mailbox-scoped service token and save its one-time plaintext securely.
6. Create a webhook and queue a test event.
7. Confirm the durable webhook job reaches delivered and an attempt record is written.
8. Send transactional test mail with a stable idempotency key and confirm status becomes accepted.

Incident Triage

Site unreachable

1. fly status --app zmail-zergai
2. fly checks list --app zmail-zergai
3. fly logs --app zmail-zergai --no-tail

Domain resolves to parked page

1. Verify DNS A/CNAME records in registrar.
2. Remove parked/forwarding records.
3. Confirm cert and app mapping in Fly.

SMTP send failures

1. Inspect outbox errors in logs.
2. Verify outbound DNS and recipient MX reachability.
3. Validate SPF/DKIM/DMARC alignment.

Webhook failures

1. Check /app/api/webhooks/{id}/deliveries.
2. Validate endpoint TLS and 2xx responses.
3. Verify secret/signature handling in receiver.