MailFlatDocs
HomeEmail testing APIOpen dashboard
Documentation/Getting Started/Quickstart & Concepts

Quickstart & Concepts

One account, three surfaces: web inbox, developer API, and AI agents. All share the same encrypted, auto-purging infrastructure.

Four steps to your first inbox

  1. Open an inbox
    Click + and type a name, e.g. shop. You get shop@a7f2c.mailflat.net, a real and permanent address.
  2. Use it anywhere
    Sign up to a site with it. The mail lands here and any verification code is pulled out and shown as a chip you can copy in one click.
  3. Read, reply, send
    From the web inbox, or let code do it with an API key. Outgoing mail leaves from your address, DKIM-signed.
  4. Forget about it
    Messages purge themselves on your plan's timer. The address stays, ready to reuse, until you delete it yourself.
Permanent address, temporary messages
This is the one thing that surprises people coming from throwaway-mail sites: the address does not expire. Only the mail inside it does.

The vocabulary

Every MailFlat address follows this shape.
InboxA real address you own
name@namespace.mailflat.net, or an address on your own domain. Permanent until you delete it; every inbox can both receive and send.
RetentionHow long messages survive
A per-inbox window, capped by your plan: two hours on Free, up to a month on paid plans. When a message is older than the window it is deleted, permanently.
Tagshop+promo@… → filter by #promo
Anything after a + lands in the same inbox but stays filterable, a per-service label that tells you exactly who shared your address.
OTPVerification codes, extracted for you
Codes are detected as mail is stored, so they are available both as a chip in the UI and as otp_code on the API. Encryption turns this off by design.
PoolsFor everyone · For agents · Testing
Inboxes for humans can be end-to-end encrypted. Inboxes for agents are always plain text so the API can read them. Testing is the agent pool with a ci tag for throwaway run inboxes.

Or start from code

Create an account key in Agents → API keys, then pick your language. All three do the same thing: open an inbox and wait for a code.
curl -X POST https://mailflat.net/api/v1/inboxes \
-H "X-API-Key: mf_live_…" \
-d '{"prefix":"agent-7f3","retention_hours":2}'
# → { "address": "agent-7f3@a7f2c.mailflat.net" }
Full reference in Agent API & MCP; every SDK wraps the same endpoints.