SMTP Server
A self-hosted, multi-tenant transactional email platform on FastAPI + AWS SES — domain onboarding, a gated send pipeline backed by SQS, email verification, deliverability analytics, and a live SSE event stream.
Overview
OrbitAIM SMTP Server is a production FastAPI backend that turns AWS SES into a full multi-tenant email platform. Each tenant onboards a sending domain and is handed the exact CNAME/MX/TXT DNS records (DKIM, custom MAIL FROM, SPF, DMARC) to publish, then polls until SES verification flips to ready-to-send. Every message goes through a single strict pipeline — verify → suppress → throttle → stamp → send — where the first two are synchronous gates and the rest run asynchronously off an SQS queue, so accepted sends return instantly as queued. Delivery outcomes flow back through SES → SNS webhooks and surface as live Server-Sent Events, tenant-scoped reputation, and aggregated analytics sourced entirely from AWS (Virtual Deliverability Manager + Message Insights).
Key features
Automated Domain Onboarding
POST /onboarding/domain provisions an SES config set + SNS topic, registers the domain identity, and returns the exact CNAME/MX/TXT records (DKIM, custom MAIL FROM, SPF, DMARC) to publish. A status endpoint polls SES until ready_to_send flips true.
Gated Send Pipeline
POST /pipeline/send is the only send route. It runs verify → suppress as strict synchronous gates, then queues throttle → stamp → send to SQS — returning queued:true instantly and stopped_at on gate rejection.
Soft & Hard Email Verification
Synchronous soft verification (syntax, disposable-domain, MX, known-invalid registry, tenant suppression) and an async hard tier that adds SES address insights and returns a pollable job id.
AWS-Sourced Analytics
POST /analytics returns sent/delivered/bounced/complained/opens/clicks and rates, auto-routing between Message Insights, SES bulk export, and Virtual Deliverability Manager (with a day-by-day time series) based on the fields supplied.
Live Event Stream (SSE)
GET /events/live is a Server-Sent Events feed of pipeline + SES webhook activity (queued, verify-failed, suppressed, Delivery, Bounce, Complaint, Open, Click) as it happens, optionally filtered by tenant.
SES Reputation & Account Health
GET /health/aws and /account expose system-wide and per-tenant sending status, enforcement state, quotas, and bounce/complaint rates — pulled straight from SES with no local DB dependency.
Suppression & Unsubscribe Handling
Per-tenant suppression lists and unsubscribe routes keep known-bad and opted-out addresses out of the send path before any SES quota is spent.
Built with
Relying on hosted email providers meant paying per-message fees, having no per-tenant reputation isolation, and being unable to inspect the raw delivery pipeline. OrbitAIM needed its own sending infrastructure — one that could onboard a customer domain end-to-end, enforce verification and suppression before spending SES quota, and report deliverability without a third party in the loop.
Replaces third-party email services (SendGrid / Mailgun) with an owned, multi-tenant transactional email platform built directly on AWS SES — giving OrbitAIM full control over deliverability, per-tenant reputation, and cost at scale.
Engineering challenges
Making sends non-blocking without losing delivery guarantees — the pipeline runs verify → suppress synchronously as hard gates, then hands off throttle → stamp → send to an SQS-backed background consumer so the API responds 'queued' in milliseconds.
Fully automated domain onboarding — provisioning an SES config set, an SNS topic, and a domain identity per tenant, then returning ready-to-paste DKIM/MAIL-FROM/SPF/DMARC DNS records and polling verification status.
Two-tier email verification — a synchronous 'soft' check (syntax, disposable-domain, MX, known-invalid registry, tenant suppression list) and an async 'hard' check that adds SES address insights and returns a pollable job id.
Sourcing all analytics from AWS rather than a local counter — routing between Message Insights (single message), SES bulk export jobs (per-campaign, up to ~90s), and Virtual Deliverability Manager (fast tenant-wide time series) based purely on which fields the caller supplies.
Streaming pipeline + SES webhook events live to browsers over SSE with keep-alive framing, while EventSource can only issue GET with no custom headers.
Key decisions
AWS SES as the sending substrate with everything else built in-house — reuses existing AWS IAM and keeps all mail data inside the AWS boundary while owning the pipeline logic.
SQS between accept and send — decouples the request lifecycle from SES rate limits, gives natural throttling, and keeps the send route fast and idempotent via a caller-supplied unique message_id.
Caller-generated system-wide-unique message_id as the join key — the same id is later used for /pipeline/status and /analytics, so no server-side id reconciliation is needed.
100% AWS-sourced analytics (VDM + Message Insights) instead of a local metrics table — a single source of truth for delivery, bounces, complaints, opens, and clicks.
Per-tenant SES config set + SNS topic — isolates reputation and event routing so one tenant's bounce rate never contaminates another's.
asyncpg pool with a singleton DatabaseManager and SQS consumer tasks started/stopped inside the FastAPI lifespan for clean startup and shutdown.