Inboxes, TTL & catch-all

An inbox is one email address on one of your domains. Every inbox belongs to a workspace.

Permanent vs. disposable

	Disposable	Permanent
Created with	ttl_minutes: 60	ttl_minutes: null
After expiry	Rejects new mail, stays readable for 24 h, then deleted with all files	Lives until deleted
Typical use	Sign-ups, E2E tests, one-off agent tasks	Team addresses, long-lived agents

If you omit ttl_minutes, the workspace default applies (Settings → General, initially 60 minutes). Instances can force disposable-only mode with FEATURE_PERMANENT_INBOXES=false and cap lifetimes with MAX_TTL_HOURS.

Extend or convert at any time:

curl -X PATCH https://app.squadmail.dev/api/v1/inboxes/$INBOX 
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" 
  -d '{"extend_minutes": 1440}'     # or {"ttl_minutes": null} for permanent

Addresses

• Omit local_part and Squadmail generates a readable one: swift-otter-4821.
• Local parts allow a-z 0-9 . _ + -, up to 64 characters. postmaster, abuse and similar are reserved.
• Sub-addressing works: mail to name+anything@domain lands in name@domain.
• Anywhere an inbox id is expected you can pass the full address instead.

Agent attribution

Pass agent_name (or let the API key’s name be used). The dashboard groups activity by agent, and you can filter inboxes by agent.

Sender rules

{ "allow_senders": ["github.com", "noreply@stripe.com"], "block_senders": ["spam.example"] }

Entries are full addresses or domains (subdomains match). Mail that fails the rules is rejected at SMTP time and logged as an event — never silently dropped.

Overflow

max_emails caps how many messages an inbox keeps. overflow: "drop_oldest" (default) removes the oldest mail; "reject" refuses new mail while full.

Catch-all

With catch-all enabled on a domain, the first mail to an unknown address creates an inbox (tagged catch-all) in the workspace that owns the setting. Great for “give every customer/test its own address” without an API call.

Lifecycle of a message

1. Amazon SES accepts the message, stores it in S3 and notifies the Worker through SNS (signature-verified).
2. Inbox lookup, expiry, sender rules, size and flood checks.
3. MIME parsing, HTML sanitisation, OTP/magic-link extraction.
4. Row inserted as processing; raw MIME and attachments written to R2.
5. Flipped to ready atomically — the API never returns half-stored mail.
6. Live event to dashboards and waiting agents, then labeling and webhooks via the queue.