GitHub - 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. · GitHub

Skip to content

Navigation Menu

Toggle navigation

Sign in

Appearance settings

PlatformAI CODE CREATIONGitHub CopilotWrite better code with AIGitHub SparkBuild and deploy intelligent appsGitHub ModelsManage and compare promptsMCP RegistryNewIntegrate external toolsDEVELOPER WORKFLOWSActionsAutomate any workflowCodespacesInstant dev environmentsIssuesPlan and track workCode ReviewManage code changesAPPLICATION SECURITYGitHub Advanced SecurityFind and fix vulnerabilitiesCode securitySecure your code as you buildSecret protectionStop leaks before they startEXPLOREWhy GitHubDocumentationBlogChangelogMarketplaceView all featuresSolutionsBY COMPANY SIZEEnterprisesSmall and medium teamsStartupsNonprofitsBY USE CASEApp ModernizationDevSecOpsDevOpsCI/CDView all use casesBY INDUSTRYHealthcareFinancial servicesManufacturingGovernmentView all industriesView all solutionsResourcesEXPLORE BY TOPICAISoftware DevelopmentDevOpsSecurityView all topicsEXPLORE BY TYPECustomer storiesEvents & webinarsEbooks & reportsBusiness insightsGitHub SkillsSUPPORT & SERVICESDocumentationCustomer supportCommunity forumTrust centerPartnersView all resourcesOpen SourceCOMMUNITYGitHub SponsorsFund open source developersPROGRAMSSecurity LabMaintainer CommunityAcceleratorGitHub StarsArchive ProgramREPOSITORIESTopicsTrendingCollectionsEnterpriseENTERPRISE SOLUTIONSEnterprise platformAI-powered developer platformAVAILABLE ADD-ONSGitHub Advanced SecurityEnterprise-grade security featuresCopilot for BusinessEnterprise-grade AI featuresPremium SupportEnterprise-grade 24/7 supportPricing

Search or jump to...

Search code, repositories, users, issues, pull requests...

Search

Clear

Search syntax tips

Provide feedback

We read every piece of feedback, and take your input very seriously.

Include my email address so I can be contacted

Cancel

Submit feedback

Saved searches

Use saved searches to filter your results more quickly

Name

Query

To see all available qualifiers, see our documentation.

Cancel

Create saved search

Sign in

Sign up

Appearance settings

Resetting focus

You signed in with another tab or window. Reload to refresh your session.
You signed out in another tab or window. Reload to refresh your session.
You switched accounts on another tab or window. Reload to refresh your session.

Dismiss alert

craigmccaskill

/

posthorn

Public

Notifications
You must be signed in to change notification settings

Fork
0

Star
7

Code

Issues
23

Pull requests
0

Discussions

Actions

Projects

Security and quality
0

Insights

Additional navigation options

Code

Issues

Pull requests

Discussions

Actions

Projects

Security and quality

Insights

craigmccaskill/posthorn

 mainBranchesTagsGo to fileCodeOpen more actions menuFolders and filesNameNameLast commit messageLast commit dateLatest commit History82 Commits82 Commits.github.github  corecore  docsdocs  sitesite  specspec  .gitignore.gitignore  CHANGELOG.mdCHANGELOG.md  CLAUDE.mdCLAUDE.md  CODE_OF_CONDUCT.mdCODE_OF_CONDUCT.md  CONTRIBUTING.mdCONTRIBUTING.md  LICENSELICENSE  README.mdREADME.md  SECURITY.mdSECURITY.md  View all filesRepository files navigationREADMECode of conductContributingApache-2.0 licenseSecurityPosthorn

The unified outbound mail layer for self-hosted projects. One gateway between every app you self-host and the transactional mail provider you've already picked. Three ingress shapes (HTTP form, HTTP API, SMTP), five transports (Postmark, Resend, Mailgun, AWS SES, outbound-SMTP relay), single Go binary, single TOML config.
Real-world stacks: Hugo + Comentario · Ghost · Gitea · Umami digest cron · Cloudflare Worker
Why
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.
Posthorn is the bridge. One container, one config, one set of credentials. Your apps point at Posthorn. Posthorn talks to your provider.

Where your app connects
What Posthorn does

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.
Documentation
posthorn.dev — getting started, configuration reference, deployment guides, feature deep-dives, security model, HTTP API reference, FAQ. Ten recipes covering contact forms, newsletter signups, multi-form sites, monitoring alerts, Cloudflare Workers, internal SMTP relay (Docker Compose), and full case studies for Hugo+Comentario, Ghost, Gitea, and self-hosted Umami digests.
For project history and the v1.0 spec, see spec/.
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 = ["you@example.com"]
from = "Contact Form <noreply@example.com>"
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.
Full walkthrough: posthorn.dev/getting-started/quick-start.
API mode (server-to-server)
For Workers, cron jobs, internal services — anything that speaks JSON instead of forms:
[[endpoints]]
path = "/api/transactional"
to = ["fallback@yourdomain.com"]
from = "YourApp <noreply@yourdomain.com>"
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": "alice@example.com",
"subject_line": "Reset your password",
"message": "Click here: https://app.example.com/reset/abc"
}'
Full walkthrough: posthorn.dev/recipes/cloudflare-worker.
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.
Full doc: posthorn.dev/features/smtp-ingress.
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. See posthorn.dev/configuration/transports for per-provider config.
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. See posthorn.dev/security/dns.
Reverse proxy — Posthorn does not terminate TLS. Run it behind Caddy, nginx, or Traefik. See posthorn.dev/deployment/reverse-proxy.
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.

The full operator checklist is on posthorn.dev.
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.
Full trajectory: posthorn.dev/roadmap.
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
Contributing
The v1.0 specification is in spec/ (brief, PRD, architecture). The architecture doc at spec/03-architecture.md is the source of truth for design questions.
Security issues: see SECURITY.md — do not open public issues for security disclosures.
License
Apache-2.0. See LICENSE.

About

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.

posthorn.dev

Topics

go

docker

email

self-hosted

postmark

homelab

email-gateway

smtp-relay

transactional-email

mail-gateway

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy

Uh oh!

There was an error while loading. Please reload this page.

Activity
Stars

7
stars
Watchers

1
watching
Forks

0
forks

Report repository

Releases
1

v1.0.0 — Initial release

Latest

May 26, 2026

Packages
0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Go
59.6%

MDX
39.1%

Other
1.3%

Footer

© 2026 GitHub, Inc.

Footer navigation

Terms

Privacy

Security

Status

Community

Docs

Contact

Manage cookies

Do not share my personal information

You can’t perform that action at this time.

Posthorn is designed as a unified, self-hosted email gateway that serves as an intermediary layer between various self-hosted applications and chosen transactional mail providers, such as Postmark, Resend, Mailgun, AWS SES, or outbound-SMTP relays. The core objective of Posthorn is to eliminate the need for individual applications to manage the complexities and duplicate concerns associated with sending transactional emails, which typically involves managing API keys, retry logic, bounce handling, and sender reputation across multiple integration points. This addresses the fragmented nature of email integration where each application must independently manage communication with its chosen provider.

The system centralizes this functionality using a single architectural deployment consisting of one Docker container and a single TOML configuration file. Posthorn supports three distinct ingress shapes, allowing flexibility depending on the application's communication method: HTTP form submission, HTTP API requests, and native SMTP listening.

When handling HTTP form ingress, Posthorn implements security measures such as honeypots, validation of the Origin or Referer header, rate limiting, and optional Cross-Site Request Forgery protection. For HTTP API mode, the gateway supports authorization using bearer tokens, accepts JSON body data, and implements idempotent retries along with a mechanism for overriding specific fields for transactional sends. Furthermore, for an SMTP listener, Posthorn can handle applications natively speaking SMTP, parsing MIME messages, enforcing authentication via AUTH PLAIN or client-cert, requiring STARTTLS, and enforcing allowlists for senders and recipients. All these varied ingress methods converge into a unified transport layer that routes messages to a single chosen outbound provider.

Posthorn explicitly defines what it is not. It is not a full-fledged mail server, as it does not include mailbox storage, IMAP/JMAP services, or comprehensive DKIM key management. It is also not an outbound infrastructure provider, as it functions purely as a relay, not managing its own SMTP fleet or IP reputation. Similarly, it does not function as a marketing email platform or a webmail interface. Instead, Posthorn serves as the crucial integration layer that bridges self-hosted applications with existing transactional email services.

The system offers flexibility in selecting the outbound transport provider, which is managed through the configuration. The available transports include Postmark, Resend, Mailgun, AWS SES (using bespoke SigV4), and generic outbound-SMTP relays. Switching between these providers is achieved by modifying the TOML configuration.

The technical specification of the initial release details the implementation of these features. It includes structured handling for failure management, implementing a retry mechanism for transient or server errors and specific handling for rate-limiting (e.g., 429 responses). Logging is structured in JSON format, incorporating UUIDv4 submission IDs and SMTP session IDs for traceability. The deployment package consists of a single Go binary and a multi-architecture distroless Docker image.

The development roadmap outlines future enhancements. Version two is planned to focus on platform maturity by introducing features like an SQLite submission log, a retry queue that persists across restarts, a suppression list for hard bounces, durable idempotency, and lifecycle event callbacks via HMAC-signed webhooks. Version three suggests speculative features including an administrative user interface, a proof-of-work spam challenge, and PGP encryption. The architecture documentation and specification details the design choices, with the architecture document serving as the source of truth for design inquiries.