jkaninda/posta repository overview

⁠Posta

Self-hosted email delivery & inbound platform for developers and teams

Overview⁠ · Quick Start⁠ · Features⁠ · Architecture⁠ · API⁠ · Dashboard⁠ · SDKs⁠ · Live Demo⁠ · Docs⁠

⁠Overview

Posta is a self-hosted, developer-first email platform that handles outbound, inbound, and relayed email — driven by a single HTTP API, with SMTP available for the paths that need it.

• Outbound — send transactional and marketing email over your own SMTP, with templates, localization, campaigns, subscriber lists, bounce and complaint handling, and delivery analytics.
• Inbound — receive email at your domains, parse messages and attachments, and forward the structured payloads to your application via webhooks.
• Relay — point an existing SMTP client at Posta and its mail flows through the same outbound pipeline as the API, so you can migrate to the HTTP API at your own pace.

It is designed as a fully self-hostable alternative to services like SendGrid, Mailgun, and Postmark — giving you complete ownership of your email infrastructure, data, and deliverability.

⁠Quick Example

Send your first email:

curl -X POST http://localhost:9000/api/v1/emails/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <[email protected]>",
    "to": ["Jonas Kaninda <[email protected]>","[email protected]"],
    "subject": "Hello from Posta",
    "html": "<h1>Hello!</h1>"
  }'

Response:

{
  "id": "0ae4b04e-5c64-4b2f-bad6-460f8d5d98b3",
  "status": "queued"
}

⁠Core Features

⁠Email Delivery

• REST API for transactional, batch, and templated emails
• Attachments, custom headers, and unsubscribe support
• Web view ("view in browser") with signed, expiring links
• Scheduled sending and preview mode
• Email address verification (syntax, MX, disposable & role-account checks)
• Async processing with Redis and Asynq
• Automatic retries and priority queues

⁠Inbound Email

• Built-in SMTP receiver with TLS
• HTTP webhook ingest with HMAC verification
• Raw message, headers & attachment storage
• Forwarding with status tracking
• Spam scoring & retry on failure
• Real-time SSE stream for inbound notifications

⁠Email Relay

• Point an existing SMTP client at Posta — no code changes
• Relays into the same pipeline as the send API
• Domain verification, suppression & rate limits still apply
• Workspace-scoped credentials with IP allowlist
• Instant revocation, no redeploy
• Off by default — built for private networks

⁠Templates

• Versioned and multi-language templates
• Variable substitution and stylesheet inlining
• System variables for web view and one-click unsubscribe links
• Import/export and preview support

⁠Campaigns

• Bulk email campaigns with scheduling and subscriber targeting
• Draft, scheduled, sending, paused, and cancelled lifecycle states
• A/B testing with multi-variant splits and per-variant performance metrics

⁠SMTP & Domains

• Multiple SMTP providers with TLS support
• Shared SMTP pools for teams
• Domain verification (SPF, DKIM, DMARC)
• Verified sender enforcement

⁠Security

• API keys with expiration, hashing, and IP allowlisting
• JWT authentication and RBAC
• Two-factor authentication (TOTP)
• OAuth / SSO login (Google, Keycloak, authentik, and more)
• Rate limiting and session management

⁠Contacts & Subscribers

• Auto-tracked contacts with per-recipient send/failure stats
• Subscriber management with static and dynamic (segmented) lists
• Bulk import via JSON or CSV with column mapping
• Subscriber lifecycle (active, bounced, unsubscribed)
• Hard/soft bounce and complaint handling with automatic suppression

⁠Unsubscribe Lists

• RFC 8058 one-click unsubscribe scoped per list
• Posta-minted signed URLs and List-Unsubscribe header
• Scoped opt-outs so receipts and password resets keep flowing
• Management API and dashboard for CRUD and opt-out browsing
• email.unsubscribed webhook event
• Resubscribe individual addresses without lifting a global block

⁠Tracking

• Pixel-based open tracking
• Click tracking with link rewriting
• Per-email engagement metrics

⁠Workspaces

• Multi-tenant architecture with isolated workspaces
• Role-based access control (owner, admin, editor, viewer)
• Member invitations and scoped API keys
• Data export/import and GDPR contact/log deletion

⁠Webhooks & Events

• Event-driven architecture with webhook delivery
• Retry strategies and delivery tracking
• Audit logs and real-time event streaming

⁠Analytics & Monitoring

• Email delivery, open, and click metrics
• Prometheus integration
• Health endpoints and daily reports

⁠Admin Platform

• User and API key management
• Global metrics and logs
• SMTP pool management
• Usage plans with quotas and per-workspace assignment
• OAuth/SSO provider configuration
• Platform configuration and retention policies

⁠Dashboard

• Vue-based UI for managing all resources
• Analytics, templates, SMTP, domains, contacts, campaigns, and logs
• Dark/light mode and user preferences

⁠Architecture

Posta ships as a single binary that runs in two modes: posta serves the HTTP API, dashboard, and SMTP listeners; posta worker consumes the job queue. Both modes are stateless — all state lives in the shared PostgreSQL, Redis, and object storage — so you can run as many workers as your send volume needs.