Guide 8 of 8
Key Concepts
Reference page for core MailFork concepts. Linked from task guides — use this when you need a precise definition of how something works under the hood.
Email Address Format
Every MailFork address is composed of four parts. The format differs slightly between team inboxes and individual (me-namespace) inboxes.
| Part | Example | Description |
|---|---|---|
| username | signup-flow | The inbox name — chosen by the user. Does not need to be "inbox". |
| +alias | +run-42 | Optional alias tag. Delivered to the inbox, tagged for filtering. Omit for the base inbox address. |
| team / username | qa | The team slug (org namespace) or username slug (me namespace). |
| org / me | acme | The org slug, or the literal string "me" for individual accounts. |
Plan-Specific Formats
Ephemeral vs Permanent Aliases
Permanent
Stays active until explicitly deleted or deactivated via the web UI or SDK. Use for stable long-lived addresses.
Ephemeral recommended for CI/CD
Has a TTL. Automatically deactivates on expiry. Recommended for CI/CD — create one per test run, no teardown needed.
| onExpire value | What happens |
|---|---|
| 'delete' | Alias deactivates. All emails tagged to it are immediately and permanently deleted. |
| 'keep' | Alias deactivates (no new mail accepted). All previously delivered emails remain visible in the inbox under the alias tag. |
Quota & Rate Limits
Quota tracks how much of a resource you've used over a period (daily or monthly) and resets on a schedule.
Rate limits control burst speed — hitting a rate limit returns 429 with a Retry-After header.
Both are plan-dependent.
Key quota-tracked resources:
- Inbound emails per day
- API calls per day
- OTP extractions per day
- Teams per org
- Inboxes per team
Catch-All Inbox
A catch-all inbox receives email addressed to any username under a team that doesn't match an existing inbox. Useful for testing flows that generate dynamic addresses, or for capturing emails from third-party systems that send to unpredictable local parts.
API Key Scopes
| Scope | What it allows |
|---|---|
| emails:read | List emails, read email body and attachments, extract OTPs |
| emails:delete | Delete emails and permanently remove them from an inbox |
| inboxes:read | List inboxes and read inbox metadata |
| inboxes:manage | Create, update (pause/resume, catch-all), and delete inboxes |
| folders:manage | Create, rename, and delete folders |
| routing:manage | Create, update, reorder, and delete routing rules |
| api-keys:read | List API keys and read their metadata (not the key value) |
| api-keys:manage | Create, update, and revoke API keys |