Inboxes & TTLs
An inbox is a real email address your test suite owns: created in one API call, receiving on a real MX domain, and disposable by design. This page covers the address rules, the TTL lifecycle, and the caps that keep the free tier abuse-resistant.
What an inbox is
Every inbox is a local_part@domain pair — on a shared mailfixture domain by default, or on your own verified custom domain. Inboxes exist only because an authenticated API call created them: there is no catch-all. Mail to an address you never created is rejected during the SMTP session with a permanent 550, before the sender transmits the body. And mailfixture is receive-only — an inbox can never send, reply, or forward.
Creating inboxes
POST /v1/inboxes with every field optional — an empty body gets you a random address on the shared domain.
$ curl -s -X POST https://api.mailfixture.com/v1/inboxes \ -H "Authorization: Bearer $MAILFIXTURE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"local_part": "signup-run-41", "ttl_seconds": 900}'
{
"id": "0198a3e2-…",
"email_address": "signup-run-41@mxsink.sh",
"local_part": "signup-run-41",
"domain": "mxsink.sh",
"ttl_expires_at": "2026-07-07T14:32:09Z",
"created_at": "2026-07-07T14:17:09Z"
}
The fields:
local_part — omit it and we generate a random 10-character one. If you set it: 1–64 characters of a-z, 0-9, ., _, -, not starting or ending with a dot. Input is lowercased (email local parts are case-insensitive here). An address that already exists on that domain answers 409.
domain — defaults to the shared domain. Pass a custom domain's FQDN to create the inbox there; it must be verified on your account first.
ttl_seconds — see below. Omit it and the inbox lives until you delete it.
TTLs
ttl_seconds accepts 60 seconds to 30 days. When the TTL passes, the inbox stops accepting mail immediately — senders get the same 550 as for an address that never existed — and it stops counting against your active-inbox cap. An hourly sweep then deletes the inbox and every message in it.
A TTL is not a substitute for teardown; it's the backstop for the runs that never reach teardown. The pattern that works: delete the inbox in your test's cleanup hook, and set a short TTL (10–15 minutes) so a CI job that dies mid-flight can't strand inboxes against your cap.
Caps and limits
Two limits apply to inbox creation, both answered as RFC 7807 problem+json:
Active-inbox cap — concurrently existing, non-expired inboxes per account: 25 on free, 250 on solo, 1,000 on team, 5,000 on scale. At the cap, creation answers 403; delete inboxes or let TTLs expire them. Inbox-per-test suites with TTLs never accumulate toward this.
Creation velocity — per API key, creation bursts to 10 and refills at 10 per minute. Beyond that you get a 429 with Retry-After; the SDKs absorb it inside their wait helpers. This is an abuse control (shared domains attract signup farmers), not a throughput knob — parallel suites stay comfortably under it with one inbox per test.
Message-volume caps (daily and monthly) are a property of receiving, not of inboxes — they're covered in Messages.
Delete vs. clear
DELETE /v1/inboxes/{id} removes the address and all its messages immediately — the standard teardown call. POST /v1/inboxes/{id}/clear drops the messages but keeps the address: useful for a long-lived staging inbox you reset between suite runs instead of recreating.