StateSet API Docs

All configuration is by environment variable. See .env.example for the full set.

Core

Variable	Default	Notes
`STATESET_MAIL_API_KEYS`	(required)	Comma-separated bearer tokens
`DEFAULT_FROM`	(required)	Used when a send omits `from`
`DATABASE_URL`	`sqlite://data/mail.db`	SQLite file; WAL mode is enabled
`MAX_BODY_BYTES`	`26214400` (25 MB)	HTTP request size cap
`PUBLIC_BASE_URL`	unset	Public origin for tracking and unsubscribe URLs. Required for opens, clicks, and `List-Unsubscribe`

SMTP and IMAP

Variable	Default	Notes
`SMTP_HOST` / `SMTP_PORT`	`stalwart:587`	The SMTP server to relay through
`SMTP_USERNAME` / `SMTP_PASSWORD`	unset	SMTP auth
`SMTP_ENCRYPTION`	`starttls`	`starttls` \| `tls` \| `none`
`IMAP_HOST` / `IMAP_PORT`	unset / `993`	Leave blank to disable receive
`IMAP_USERNAME` / `IMAP_PASSWORD`	unset	IMAP auth
`IMAP_FOLDER`	`INBOX`
`IMAP_POLL_INTERVAL_SECS`	`15`

Sending

Variable	Default	Notes
`SEND_MAX_ATTEMPTS`	`8`	Backoff is jittered exponential
`SEND_INITIAL_BACKOFF_SECS`	`30`
`DOMAIN_THROTTLE_PER_MIN`	`120`	Per-recipient-domain send cap (token bucket)

Security and tracking

Variable	Default	Notes
`TRACKING_SECRET`	first API key	HMAC key signing every `/t/*` URL. Rotate carefully — it invalidates in-flight links
`SESSION_SECRET`	derived from `TRACKING_SECRET`	HMAC key signing dashboard session cookies. Kept distinct so the tracking key can’t forge sessions
`TRUST_PROXY_HOPS`	`0`	Proxy hops to trust when parsing `X-Forwarded-For` on tracking routes
`TRACKING_IP_PER_MIN`	`60`	Per-IP request cap on `/t/*`

Leave TRUST_PROXY_HOPS at 0 unless the service genuinely sits behind that many proxies — trusting more hops than exist lets a client spoof its IP past the tracking rate limit.

Webhooks

Multiple subscriptions live in a webhook_subscriptions table, each with its own URL, HMAC secret, and event filters supporting wildcards ("*", "flow.*", or exact names). Subscriptions can be scoped to a tenant. The legacy environment variables below seed a default subscription on first start.

Variable	Default	Notes
`WEBHOOK_URL` / `WEBHOOK_SECRET`	unset	Optional outbound event sink (legacy; seeds a default subscription)

Delivery headers

Every outbound POST carries:

Header	Value
`x-stateset-event`	The event type, e.g. `message.bounced`
`x-stateset-signature`	`sha256=<hex>` — HMAC-SHA256 of the raw body
`x-stateset-subscription`	The subscription id, when the delivery came from one

The signature value is prefixed — sha256=abc123…, not the bare hex. Strip the sha256= before comparing, or the comparison always fails.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, header, secret) {
  if (!header?.startsWith('sha256=')) return false;
  const provided = Buffer.from(header.slice('sha256='.length), 'hex');
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  // length check first — timingSafeEqual throws on a length mismatch
  return provided.length === expected.length && timingSafeEqual(provided, expected);
}

Compute the HMAC over the raw request body. Re-serialising parsed JSON will not reproduce the same bytes. Events emitted:

Transactional — message.sent, message.failed, message.bounced, inbox.received
Marketing lifecycle — campaign.started, campaign.finished, profile.subscribed, profile.unsubscribed, message.opened, message.clicked, flow.run.started, flow.run.completed

Payloads are enriched with context: inbox.received carries the conversation, mailbox, domain, and tenant plus attachment metadata; bounce events carry the recipient; engagement events carry recipient and campaign.

Webhook targets are SSRF-guarded — validated at create time, re-resolved before each send, with loopback, private, link-local, and metadata addresses refused and redirects disabled.

Inbound adapters

Variable	Notes
`SHOPIFY_WEBHOOK_SECRET`	Required to use `POST /v1/inbound/shopify`. Verifies `X-Shopify-Hmac-Sha256` — base64 HMAC-SHA256, not hex
`STRIPE_WEBHOOK_SECRET`	Required to use `POST /v1/inbound/stripe`
`INBOUND_GENERIC_SECRET`	Bearer token for `POST /v1/inbound/generic`

Managed domains and conversations

Variable	Default	Notes
`MAIL_DOMAIN`	unset	Managed mailbox domain; when set, sends from this domain must be a registered mailbox
`MAIL_MX_HOST`	`mx.<message-id domain>`	Host customers point their MX record at
`MAIL_SPF_INCLUDE`	`_spf.<message-id domain>`	SPF include customers add to their domain
`MAIL_DMARC_RUA`	unset	Optional DMARC aggregate-report address surfaced in the suggested record
`DNS_VERIFY_INTERVAL_SECS`	`60`	How often the worker re-checks unsettled managed domains
`STALWART_ADMIN_URL` / `STALWART_ADMIN_TOKEN`	unset	MTA admin API for auto-provisioning verified domains. Unset is a logged no-op
`ATTACHMENT_MAX_BYTES`	`10485760` (10 MB)	Max size of an inbound attachment retained for `fetch_attachment`
`CONVERSATION_MATCH_WINDOW_DAYS`	`30`	Fallback subject + participant threading window when RFC headers are absent

Observability

Endpoint	Purpose
`GET /v1/admin/queues`	Status counters per queue
`GET /metrics`	Prometheus text-format gauges
`GET /v1/admin/activity`	Append-only activity log, filterable — e.g. `?action=campaign.sent&limit=50`

Bulk import limits

POST /v1/profiles/bulk (JSON array), POST /v1/profiles/import (CSV body), and POST /v1/lists/:id/members/bulk are each capped at 1000 records per request.

Next steps

Conversations

The triage surface these settings configure.

MCP server

Driving the inbox from an agent.

Overview

What StateSet Mail is, before the variables.

Last modified on August 29, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Mail Configuration

Core

SMTP and IMAP

Sending

Security and tracking

Webhooks

Delivery headers

Inbound adapters

Managed domains and conversations

Observability

Bulk import limits

Next steps

Conversations

MCP server

Overview

​Core

​SMTP and IMAP

​Sending

​Security and tracking

​Webhooks

​Delivery headers

​Inbound adapters

​Managed domains and conversations

​Observability

​Bulk import limits

​Next steps

Conversations

MCP server

Overview

Core

SMTP and IMAP

Sending

Security and tracking

Webhooks

Delivery headers

Inbound adapters

Managed domains and conversations

Observability

Bulk import limits

Next steps