Skip to main content

Architecture

Three services, one Docker Compose. No Kubernetes, no orchestrators, no complexity.

                    Inbound Email
                         │
                         ▼
              ┌──────────────────┐
              │   Postfix SMTP   │
              │     (port 25)    │
              └────────┬─────────┘
                       │ pipe transport
                       ▼
              ┌──────────────────┐
              │    Hono API      │  ←── REST API (port 8000)
              │   (TypeScript)   │
              └────────┬─────────┘
                       │
                       ▼
              ┌──────────────────┐
              │   PostgreSQL     │
              │   (port 5432)    │
              └──────────────────┘

Components​

Postfix SMTP​

Production-grade MTA that handles all inbound email. Pipe transport forwards parsed mail to the API layer. Handles DKIM, SPF, and DMARC if you configure DNS records.

Hono API​

TypeScript API server (runs on Bun) exposing REST endpoints. Handles inbox CRUD, email storage, long-polling for new emails, API key authentication, and webhook dispatch.

PostgreSQL​

All data lives in PostgreSQL — inboxes, emails, API keys, raw MIME payloads. Foreign key cascades enable atomic zero-residue purges when inboxes expire or are deleted.

Data Flow​

  1. External service sends email to {inbox-id}@yourdomain.com
  2. Postfix receives on port 25 and pipes the raw MIME to the ingest handler
  3. Ingest handler parses the email, looks up the inbox by the local part (UUID before @)
  4. If the inbox exists and is active, the email is inserted into PostgreSQL
  5. Any clients long-polling on /inboxes/{id}/wait are notified immediately
  6. If the inbox doesn't exist, Postfix returns EX_NOUSER (67) to bounce the email