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 (self-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 (self namespace). |
| org / self | acme | The org slug, or the literal string "self" for individual accounts. |
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. Emails tagged to it are moved to the Transient system folder and purged after 24 hours. |
| 'archive' | Alias deactivates (no new mail accepted). All previously delivered emails remain visible in the inbox under the alias tag. |
Lean MIME
When an email arrives, MailFork strips attachment binaries from the MIME before writing the message to disk.
The attachment binaries are stored separately. The first 500 characters of plain text body are stored in Postgres
as body_preview for fast queries.
Disk — lean MIME
Raw email with attachment binaries removed. Small per-email footprint.
Disk — attachments
Attachment binaries stored separately at a deterministic path per email.
Postgres — metadata
All email metadata plus body_preview (500 chars) for fast indexed queries.
Funnel Search
Body search uses a two-stage funnel to stay fast without a full-text index.
Stage 1 — Postgres filter
Indexed columns (inbox_id, from, subject, received_at, alias_tag) are used to reduce the candidate set to 2–10 emails.
Stage 2 — Disk body scan
The MIME files for the candidates are read from disk (or in-process cache) and scanned for the body query. No full-text index needed.
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 |