​

StateSet Mail

   Agent ─HTTP/JSON─▶ stateset-mail ──SMTP──▶ Stalwart ──▶ Internet
                          │            ◀──IMAP──┘            │
                          │                                  │
                          └──webhook──▶ Your service ◀──bounces

​

What it covers

​

Transactional core

• Send via a persistent SQLite-backed queue with exponential-backoff retries — process restarts don’t lose mail.
• Receive via an IMAP polling worker. New messages land in /v1/inbox/messages.
• Bounce correlation — DSN replies are parsed, matched against the outbound Message-ID we assigned, and the original send is marked bounced. Hard (5.x) bounces are auto-added to the suppression list.
• Webhooks for message.sent, message.failed, message.bounced, and inbox.received, with HMAC-SHA256 signatures and durable retries.
• Tool schemas at /v1/tools in both OpenAI and Anthropic formats.
• Idempotency keys so a retried tool call doesn’t double-send.

​

Marketing automation

• Profiles — contacts with arbitrary JSON properties, consent state, and timezone.
• Lists (static) and Segments (saved JSON rule trees over properties and the event log). Property rules compile down to a single SQL WHERE for O(matching) evaluation.
• Templates — Handlebars merge tags for subject, html_body, text_body, and preheader. Validated at create time, rendered per recipient at send time. Templates also accept mjml_source and auto-compile to inline-styled responsive HTML.
• Campaigns — one-shot broadcast to a list or segment, with a per-domain token bucket to avoid hammering a single MX. Live stats: sent, failed, suppressed, opens, unique opens, clicks, unique clicks, unsubscribes, bounces.
• A/B testing — an optional variants array of {label, template_id, weight, subject_override?}. Recipients are hash-bucketed deterministically by (campaign_id, profile_id), so re-runs see the same assignment. Stats split per variant.
• Flows — event-triggered automations (signup → send welcome → wait 24h → send tips). Multi-step, durable, and they survive restarts.
• Open / click tracking — a 1×1 pixel plus a link rewriter that proxies through the service and writes to a tracking event log.
• One-click unsubscribe — RFC 8058 List-Unsubscribe and List-Unsubscribe-Post headers plus a footer link. Honoring it suppresses the address and flips the profile’s consent to unsubscribed.
• Suppression list — auto-populated from hard bounces, unsubscribes, and complaints. Checked at enqueue and at send time.
• Hosted signup forms — public GET /f/:id renders an HTML form, POST /f/:id collects subscribers, with optional double opt-in. Admin CRUD under /v1/forms.
• Engagement-based segments — an engagement leaf rule supporting opened | clicked | sent | bounced | unsubscribed × occurred | did_not_occur | count, optionally scoped to a specific campaign.
• Time-series analytics — GET /v1/campaigns/:id/timeseries?metric=opens|clicks|sent|bounced|unsubscribed&bucket=hour|day.

​

Production hardening

• HMAC-signed tracking URLs — every /t/o/, /t/c/, /t/u/ URL carries ?s=<16-byte hmac>. Unsigned or mismatched requests get a 404 with no DB writes, closing the open-redirect risk on click tracking.
• Per-IP tracking rate limit — a token bucket (TRACKING_IP_PER_MIN) blocks pixel-fetch amplification. TRUST_PROXY_HOPS tells the tracking routes how far back to walk X-Forwarded-For; it defaults to 0 (socket peer only).
• Transactional worker claims — the campaign and flow workers take SQLite’s RESERVED write lock before flipping status, so workers never double-fire a step.
• Crash recovery — rows a worker claimed but never completed are reclaimed. The outbound worker reaps stale sending rows back to pending, mirroring the flow worker’s orphan sweep. Nothing is silently lost on restart.
• Graceful shutdown — on SIGINT/SIGTERM the HTTP server drains, then every background worker is signalled and joined before exit.
• SSRF-guarded webhooks — outbound webhook targets are validated at create time and re-resolved before each send. Loopback, private, link-local, and metadata addresses are refused, and redirects are disabled.
• Send-time windows — send_window_start_hour, send_window_end_hour, and send_timezone on campaigns, plus timezone on profiles. Messages outside the window defer to the next local window start with no attempt recorded.
• Activity log — an append-only table capturing (actor fingerprint, action, resource_type, resource_id, payload) on every mutating handler. The actor is sha256(api_key)[:8] — enough to attribute, not enough to recover the key.
• Observability — GET /v1/admin/queues for per-queue status counters and GET /metrics for Prometheus text-format gauges.

​

Inbound webhook adapters

​

Web dashboard

​

Next steps