Authentication & API Keys
How to authenticate programmatic access to your inbox infrastructure.
Two kinds of API keys: which one do I use?
MailFlat gives you two ways to authenticate automation. They differ only in scope, meaning how much they can touch.
| Account key | Inbox key | |
| Looks like | mf_live_… | mf_… |
| Scope | All inboxes in your account | One single inbox |
| Can create inboxes? | ✅ yes | ❌ no (already tied to one) |
| Where to find it | Agents → API keys | Open the inbox → 🔑 in the header |
| Header | X-API-Key: mf_live_… | X-API-Key: mf_… |
| Best for | Your own agents/CI that spin up many inboxes | Sharing just one inbox with a third party |
Rule of thumb
Use the account key when your code manages many inboxes. Use an inbox key when you want to hand exactly one inbox to someone else without exposing the rest of your account.
Wrong key, wrong path → 401
Account keys work on /api/v1/…; inbox keys work on /api/inboxes/{addr}/…. A valid inbox key on a v1 path still returns 401. It is the most common integration mistake.
Auth, three ways
• UI / session: Authorization: Bearer <token>, from login/signup. Full account in the browser.
• Account key: X-API-Key: mf_live_…, all inboxes (Agents → API keys).
• Inbox key: X-API-Key: mf_…, one inbox only (🔑 in the inbox header).
Example: Account key (manage many inboxes)
Classic agent flow: create an inbox, sign up somewhere, poll for the OTP.
# 1) create a fresh inbox
curl -X POST https://mailflat.net/api/v1/inboxes \
-H "X-API-Key: mf_live_abc123…"
# → { "address": "agent-7f3a@xxxx.mailflat.net" }
# 2) list every inbox the account owns
curl https://mailflat.net/api/v1/inboxes -H "X-API-Key: mf_live_abc123…"
# 3) poll the latest mail (OTP auto-extracted)
curl https://mailflat.net/api/v1/inboxes/agent-7f3a@xxxx.mailflat.net/latest \
-H "X-API-Key: mf_live_abc123…"
# → { "otp": "482913", "subject": "Your code", … }
Example: Inbox key (share just one inbox)
Open the inbox, click 🔑 in the header to reveal/copy its key. This key sees only that inbox.
# read messages of THIS inbox only
curl https://mailflat.net/api/inboxes/you@xxxx.mailflat.net/emails \
-H "X-API-Key: mf_9d2f8a…"
# trying another inbox with this key → 401/403
curl https://mailflat.net/api/inboxes/someone-else@…/emails \
-H "X-API-Key: mf_9d2f8a…" # ✗ denied