Core concepts

MailStack is organized around a handful of primitives. Understanding them makes the rest of the API obvious.

Organizations

Every resource — domains, keys, messages, usage — belongs to an organization. Your API key resolves to exactly one org, and all reads and writes are automatically scoped to it. Billing and the free-tier allowance are also tracked per organization.

Sending domains

A sending domain is a domain you've proven you own and configured for email authentication. Each domain carries a status (Pending → Verified) and a set of DNS records to publish: a DKIM record (Easy DKIM), an SPF entry, and a custom MAIL FROM record for alignment. You can only send from a verified domain. See Domains & DKIM.

API keys

API keys authenticate requests. Each key is prefixed with ms_live_, carries one or more scopes (for example emails:send), and may have an expiry. The full secret is returned only once at creation; MailStack stores just the visible prefix and a hash. Revoke a key at any time with DELETE /v1/api-keys/{id}.

Messages & status

Each accepted send creates a message with a stable id. A message moves through queued → sent, or ends in bounced/failed with an error. Look up any message with GET /v1/emails/{id} to retrieve its current status, the provider message id, recipients, subject, and timestamps.

Suppression

The suppression list protects your sender reputation. When a recipient hard bounces or files a complaint, their address is automatically suppressed for your organization. Subsequent sends to a suppressed address are rejected before they leave the queue, so you can't accidentally keep mailing an address that's hurting you.

Templates

Templates are reusable email designs built in the visual builder and versioned over time. Reference a template by id when sending and pass variables to fill it in. Inline bodies also support variable substitution, so you can template ad hoc without saving a design.

Webhooks

Webhooks push delivery events (delivered, bounced, complained, opened, clicked) to an endpoint you control, so your system can react in real time instead of polling. See Webhooks.

Usage & billing

MailStack is usage-only: 3,000 emails per month are free, then $0.40 per 1,000. A per-organization usage counter tracks accepted sends for the current period, and an optional spend cap pauses sending once projected overage hits your limit. Read the current period with GET /v1/billing/usage.