Concepts
Retention, limits & quotas
How long mail is kept and how to cap usage per workspace.
Retention
A cron job runs every 15 minutes:
- Inboxes that expired more than 24 hours ago are deleted with all mail and R2 objects.
- Emails older than
RETENTION_DAYS(default 30; on Squadmail Cloud the plan’s retention) are deleted — starred mail is kept. inbox.expiredwebhooks fire shortly after an inbox expires.- Events older than 30 days and webhook deliveries older than 14 days are pruned.
Limits
On self-hosted instances all limits are instance variables and apply per workspace. 0 means unlimited. On Squadmail Cloud the plan sets them, with monthly quotas per billing period.
| Variable | Default | Meaning |
|---|---|---|
MAX_INBOXES | 0 | Inboxes per workspace |
MAX_EMAILS_PER_DAY | 0 | Inbound mail per workspace per UTC day |
MAX_TTL_HOURS | 0 | Longest lifetime of a disposable inbox |
MAX_MEMBERS | 0 | Members per workspace |
MAX_API_KEYS | 0 | Active keys per workspace |
MAX_ATTACHMENT_MB | 10 | Larger attachments are skipped (and logged) |
MAX_MESSAGE_MB | 25 | Larger messages are rejected |
SEND_PER_DAY | 0 | Outbound mail per workspace per day |
LABEL_CALLS_PER_DAY | 0 | Clef calls per workspace per day |
LABEL_GLOBAL_DAILY_BUDGET | 0 | Clef calls across the whole instance per day |
API_RATE_PER_MIN | 600 | Requests per API key per minute |
Hitting a limit returns 429 with the limit and reset time:
{ "error": { "code": "limit_reached", "message": "Inbox limit reached (25).", "limit": 25 } }Flood protection
Independently of quotas, each inbox accepts at most 120 messages per minute and each sender domain 60 per minute per workspace. Excess mail is dropped and logged in the event log.
Usage
Settings → Usage & limits (self-hosted) or Plan & billing (Squadmail Cloud) shows usage against your limits. Counters are stored per day in D1.