Self-Host Quickstart

Full email stack in a single Docker Compose. Your servers, your data, your rules. MIT licensed, free forever.

Prerequisites

Requirement	Details
Server	Any Linux VPS with Docker. 1 vCPU / 1GB RAM minimum, 2 vCPU / 2GB recommended.
Domain	A domain or subdomain with an MX record pointing to your server's IP.
Docker	Docker Engine 20.10+ and Docker Compose V2.
Port 25	SMTP requires port 25 open. Some cloud providers block it — check your firewall.

Steps

1. Clone the repository

git clone https://github.com/edwin0x/flashmail
cd spawnmail

2. Configure environment

cp .env.example .env

Edit .env with your settings:

DOMAIN=mail.yourdomain.com
POSTGRES_PASSWORD=your-secure-password
API_SECRET_KEY=your-api-secret

3. Start the stack

docker compose up -d

→ spawnmail-api    running on :8000
→ spawnmail-smtp   running on :25
→ spawnmail-db     running on :5432

Verify it's running:

curl http://localhost:8000/health
# → { "status": "ok" }

4. Create your first API key

docker exec spawnmail-api \
    spawnmail-admin create-key --name "my-agent"
# → fm_live_abc123...def456

Test it:

curl -H "x-api-key: fm_live_abc123...def456" \
    http://localhost:8000/me
# → { "email": "admin", "inboxes_count": 0 }

When to Self-Host vs. Cloud

Self-host when...	Use cloud when...
Data residency is a hard requirement	You need custom domains with managed DNS
You need air-gapped or VPN-only access	Dedicated IPs and email reputation matter
You want zero recurring costs	You want SSO/SAML and SLA guarantees
Your team can manage Docker and DNS	Your team should ship agents, not infra
You want to customize the codebase	You want priority support and managed updates