Posthorn: The Unified Outbound Mail Layer for Self-Hosted Projects

The Problem: Outbound Email Is a Mess for Self-Hosters

Nobody wants to run a mail server in 2026. Self-hosted operators use Postmark, Resend, Mailgun, or AWS SES because they're cheap, they handle deliverability properly, and someone else worries about SPF / DKIM / DMARC / bounces / sender reputation.

But every app you self-host has to integrate with that service independently. Your contact form. Your Ghost blog's admin emails. Your Gitea magic links. Your Mastodon notifications. The Cloudflare Worker that fires a password-reset email when someone clicks the link. Each one needs its own copy of the API key, its own integration code, its own quirks around retry and bounce handling. The same outbound concern duplicated across your stack.

And on cloud hosts that block outbound SMTP — DigitalOcean, AWS Lightsail, Linode, Vultr — the SMTP-only apps don't work at all without a workaround.

Enter Posthorn

Posthorn is the bridge. One container, one config, one set of credentials. Your apps point at Posthorn. Posthorn talks to your provider.

It provides three ingress shapes:

• HTTP form (contact forms, signups, alert webhooks) — Honeypot + Origin/Referer + rate limit + optional CSRF; templates the email; sends
• HTTP API mode (workers, cron, payment handlers, internal services) — Authorization: Bearer auth; JSON body; idempotent retries; per-request to_override for transactional sends
• SMTP listener (Ghost, Gitea, Mastodon, Matrix, NextCloud, Authentik, anything that emits SMTP) — AUTH PLAIN or client-cert; STARTTLS-required; sender + recipient allowlists; parses MIME; forwards via HTTP API transport

All three ingresses converge on one transport.Message and one outbound provider — pick from Postmark, Resend, Mailgun, AWS SES, or an outbound-SMTP relay.

What Posthorn Is Not

To save you a wrong turn:

What it does	Look at instead
Not a mail server — No mailbox storage, no IMAP/JMAP, no DKIM key management, no MX target	Stalwart, Mailcow, iRedMail
Not its own outbound infrastructure — Posthorn relays through a provider you chose; it doesn't run its own SMTP fleet or manage IP reputation	Postal, Hyvor Relay
Not a marketing email platform — No list management, no segmentation, no campaign dashboard	Listmonk
Not webmail / a mailbox UI — No interface for reading mail	Roundcube, Snappymail (with a mail server)

The wedge is the integration layer between your self-hosted apps and the transactional provider you've already picked.

Quick Start (Docker)

# docker-compose.yml
services:
  posthorn:
    image: ghcr.io/craigmccaskill/posthorn:latest
    restart: unless-stopped
    volumes:
      - ./posthorn.toml:/etc/posthorn/config.toml:ro
    environment:
      POSTMARK_API_KEY: ${POSTMARK_API_KEY}
    ports:
      - "127.0.0.1:8080:8080" # bind to loopback; reverse-proxy from your front door

# posthorn.toml
[[endpoints]]
path = "/api/contact"
to = ["[email protected]"]
from = "Contact Form <[email protected]>"
honeypot = "_gotcha"
allowed_origins = ["https://example.com"]
required = ["name", "email", "message"]
subject = "Contact from {{.name}}"
body = """
From: {{.name}} <{{.email}}>

{{.message}}
"""
redirect_success = "/thank-you"

[endpoints.transport]
type = "postmark"

[endpoints.transport.settings]
api_key = "${env.POSTMARK_API_KEY}"

[endpoints.rate_limit]
count = 5
interval = "1m"

Reverse-proxy /api/contact from your front door (Caddy, nginx, Traefik) to http://posthorn:8080. Point your form's action at /api/contact. Done.

API Mode (Server-to-Server)

For Workers, cron jobs, internal services — anything that speaks JSON instead of forms:

[[endpoints]]
path = "/api/transactional"
to = ["[email protected]"]
from = "YourApp <[email protected]>"
auth = "api-key"
api_keys = ["${env.WORKER_KEY_PRIMARY}", "${env.WORKER_KEY_BACKUP}"]
required = ["subject_line", "message"]
subject = "{{.subject_line}}"
body = "{{.message}}"

[endpoints.transport]
type = "postmark"

[endpoints.transport.settings]
api_key = "${env.POSTMARK_API_KEY}"

curl -X POST https://posthorn.yourdomain.com/api/transactional \
  -H "Authorization: Bearer $WORKER_KEY_PRIMARY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: reset:user-123:$(date -u +%FT%H)" \
  --data '{
    "to_override": "[email protected]",
    "subject_line": "Reset your password",
    "message": "Click here: https://app.example.com/reset/abc"
  }'

SMTP Listener (Ghost / Gitea / Mastodon / Authentik)

For apps that speak SMTP natively and can't be reconfigured to call an HTTP API:

[smtp_listener]
listen = ":2525"
require_tls = true
tls_cert = "/etc/posthorn/cert.pem"
tls_key = "/etc/posthorn/key.pem"
auth_required = "smtp-auth"
allowed_senders = ["*@yourdomain.com"]
max_recipients_per_session = 10
max_message_size = "1MB"

[[smtp_listener.smtp_users]]
username = "ghost"
password = "${env.GHOST_SMTP_PASSWORD}"

[smtp_listener.transport]
type = "postmark"

[smtp_listener.transport.settings]
api_key = "${env.POSTMARK_API_KEY}"

Point Ghost (or any app's SMTP config) at posthorn.yourdomain.com:2525 with the username/password above. Posthorn parses the MIME, builds a transport.Message, forwards via Postmark.

Picking a Transport

Transport	Best for	Auth	Body
Postmark	Transactional email, strong deliverability defaults	X-Postmark-Server-Token	JSON
Resend	Modern HTTP API, developer-friendly dashboard	Authorization: Bearer	JSON
Mailgun	Higher-volume transactional, US + EU regions	HTTP Basic	multipart/form-data
AWS SES	AWS-native deployments, cheapest at volume	AWS SigV4 (bespoke)	JSON
Outbound SMTP	Any STARTTLS-capable relay (Mailtrap, your Postfix smarthost, etc.)	AUTH PLAIN	SMTP DATA

Switching providers is a TOML edit — every transport implements the same Transport interface.

Production Checklist

Before pointing real traffic at Posthorn:

• DNS — SPF, DKIM, and DMARC records on your sending domain. Without these your mail goes to spam.
• Reverse proxy — Posthorn does not terminate TLS. Run it behind Caddy, nginx, or Traefik.
• allowed_origins (form-mode endpoints) — set this to lock submissions to your domain. Without it, anyone can POST to your endpoint.
• rate_limit — set a tight bucket per endpoint (5/minute is a sensible default for a public contact form; API mode rate-limits per matched key).
• trusted_proxies — if behind a reverse proxy, list its CIDR (or use the cloudflare named preset) so the rate limiter sees the real client IP.
• /healthz and /metrics — auto-registered on the same listener. Wire your Docker healthcheck or Prometheus scrape to these.

What's in v1.0

Block	Detail
Form ingress	Form-encoded + multipart bodies; honeypot, Origin/Referer fail-closed, rate limit, optional CSRF tokens
API mode	auth = "api-key" with Bearer tokens (constant-time compare); JSON content type; idempotency keys (24h, in-memory LRU); per-request to_override
Transports	Postmark, Resend, Mailgun, AWS SES (bespoke SigV4), outbound-SMTP relay
SMTP listener	TCP listener with AUTH PLAIN / client-cert, STARTTLS-required, sender + recipient allowlists, size cap, MIME → transport.Message
Operations	/healthz, /metrics (Prometheus exposition), dry-run mode, IP-stripping, named trusted_proxies presets (Cloudflare)
Failure handling	1 retry on transient/5xx (1s), 1 retry on 429 (5s), 10s hard timeout
Logging	Structured JSON; UUIDv4 submission IDs and SMTP session IDs; transport_message_id in submission_sent
Deployment	Single Go binary, multi-arch distroless Docker image at ghcr.io/craigmccaskill/posthorn

Three external Go dependencies in the whole module: TOML parser, UUID library, LRU cache. Every transport is bespoke — no vendor SDK in transport code.

Roadmap

• v2 — platform maturity. SQLite submission log, retry queue across restarts, suppression list (auto on hard bounces), durable idempotency, lifecycle event callbacks via HMAC-signed webhook, RFC 8058 one-click unsubscribe, file attachments, HTML body, multiple outputs per endpoint (email + webhook + log fan-out), multi-tenant SMTP routing.
• v3 — speculative. Admin UI, proof-of-work spam challenge, PGP encryption. Depends on community traction.

Build from Source

Requires Go 1.25+.

git clone https://github.com/craigmccaskill/posthorn
cd posthorn/core
go build -o /tmp/posthorn ./cmd/posthorn
/tmp/posthorn version

Conclusion

Posthorn solves a real pain point for self-hosted operators: the fragmentation of outbound email integration. By providing a single, unified gateway with multiple ingress shapes and transport backends, it dramatically simplifies your email infrastructure. One container, one config, one set of credentials — and you're done.

Source

craigmccaskill/posthorn: Self-hosted email gateway between your apps and a transactional mail provider (Postmark, Resend, Mailgun, AWS SES, or outbound-SMTP). Three ingress shapes (HTTP form, HTTP API, SMTP). One Docker container, one TOML config.