Overview

Mailman is a durable email substrate — the single source of truth for message state, threading, and deliverability. It provides a REST API and webhook interface for applications that need to send, receive, and track email without managing the complexity of email infrastructure directly.

Goals

1. Centralize all mail I/O through a trusted AWS layer (SES, S3, SQS, RDS)
2. Guarantee message integrity — RFC-compliant threading, signed delivery, full audit trail
3. Expose clean REST and webhook interfaces for external systems to send and react to mail
4. Maintain high deliverability via DKIM/SPF/DMARC compliance and reputation management
5. Stay fully IaC-driven with Terraform modules for reproducible infrastructure
6. Isolate fast-moving app logic from this stable, reputation-critical core

Non-Goals

• User-facing email client — Mailman is infrastructure, not a product UI
• Marketing automation — No drip campaigns, templates, or analytics beyond deliverability
• Multi-tenant SaaS — Single-tenant deployment per environment
• IMAP/POP3 access — REST API only, no legacy protocols

Design Principles

Reliability First

Email is reputation-critical. A single misconfiguration can land a domain on blocklists. Mailman prioritizes:

• Strict RFC compliance for headers and threading
• DKIM signing on all outbound mail (handled by SES)
• Bounce and complaint handling to protect sender reputation
• Full audit trail for debugging and compliance

Durable by Default

Every message is persisted before acknowledgment:

• Raw MIME stored in S3 (immutable record)
• Parsed metadata in Postgres (queryable state)
• SQS for reliable async processing with dead-letter queues

Simple External Interface

Consumers interact via:

• REST API for sending and querying
• Webhooks for real-time event notifications
• Customer-signed JWTs for authentication
• No direct database access, no AWS SDK required

Infrastructure as Code

All AWS resources are Terraform-managed:

• No manual console configuration
• Environment parity (dev/staging/prod from same modules)
• Version-controlled infrastructure changes

Technology Stack

Layer	Technology	Rationale
Language	Rust	Memory safety, async performance, compile-time guarantees
Runtime	Tokio	Industry-standard async runtime
HTTP	Axum	Type-safe routing, tower middleware ecosystem
Database	PostgreSQL (RDS)	Relational integrity, SQLx compile-time checks
Email Transport	AWS SES	Managed deliverability, DKIM/DMARC built-in
Storage	AWS S3	Durable blob storage for raw messages and attachments
Queuing	AWS SQS	Reliable message buffering with DLQ support
Infrastructure	Terraform	Declarative, reproducible AWS provisioning

What Mailman Does

• Receives inbound email via SES receipt rules, parses MIME, resolves threads, scans for malware (ClamAV), and stores messages.
• Sends outbound email via a queued delivery pipeline through SES with DKIM signing and suppression list enforcement.
• Tracks delivery status by processing SES event notifications (delivery, bounce, complaint) and updating message state.
• Delivers webhooks for message lifecycle events with HMAC-SHA256 signatures and exponential backoff retries.
• Manages domains with automatic SES identity provisioning, DKIM setup, and DNS verification polling.
• Manages inboxes as named receiving addresses within domains, with catch-all support and address routing.

What Mailman Does Not Do

• Act as a mail transfer agent (MTA) — it delegates to SES.
• Provide IMAP/POP3 mailbox access — it's API-only.
• Render email or provide a UI — it's a backend service.
• Handle spam scoring — it scans for malware via ClamAV but does not score spam.

Services

Mailman runs as two ECS Fargate services:

Service	Role
API	Stateless Axum HTTP server. Handles REST requests, queues outbound email to SQS.
Worker	Runs 5 concurrent polling loops: inbound processing, outbound delivery, SES telemetry, webhook dispatch, and domain verification.