Troubleshooting

Check the address you gave out. The namespace matters: shop@a7f2c.mailflat.net is a different address from shop@b91e4.mailflat.net. Copy it from the inbox rather than typing it.

Check retention. On Free, messages older than two hours are gone. If the signup mail took longer than that to arrive and you looked later, it may already have been purged.

Check your monthly quota. Once the plan's allowance is spent, incoming mail is rejected until the next month. The Billing page shows what is left.

On your own domain: the MX record is what brings mail in. If it is missing, wrong, or a second MX still points at an old provider, the mail never reaches us.

The code is pulled out when the message is stored, so it only works when we can read the body:

• Encryption is on. We hold ciphertext, so there is nothing to scan. Open the message and read the code yourself, or use a plain-text agent inbox for automation.

• The code is inside an image or a link. Some senders never put the digits in the text. Open the message and copy it manually.

• Quota reached. Sent mail counts against the same monthly allowance as received.

• The recipient's server rejected it. The failure reason is kept on the sent row in the message viewer.

• On your own domain, delivery depends on SPF and DKIM being correct. If mail lands in spam rather than bouncing, that is almost always a DNS problem, not a MailFlat one.

There are two key types and they live on different paths. Mixing them is the single most common API mistake:

An inbox key on a /api/v1 path returns 401 even though the key is perfectly valid, it simply is not an account key. And an inbox key pointed at a differentinbox is denied by design.

Inboxes created through the API are always plain text so automation can work. But an inbox created in the web pool while encryption is on is encrypted. Point the agent at an inbox from the agent pool instead, or turn encryption off if this account exists purely for automation.

The agent limit counts inboxes in the agent pool. Test inboxes tagged ci are excluded from it, so the number in the Agents tab is what counts. If you are at the limit, delete an agent inbox you no longer use, or tear down finished test batches, which frees the underlying inbox allowance.

The API allows 500 requests per hour per IP. A tight OTP loop burns that in minutes, so poll every 2–3 seconds, or switch to a webhook and stop polling entirely.

• Give DNS time. Propagation is usually minutes, occasionally an hour.

• Check the host field. Namecheap, GoDaddy and name.com want only the subdomain part (_mailflat-verify), because they append the domain for you. Cloudflare and Route 53 want the full name. Pasting the wrong form is the usual cause.

• Only one SPF record. If the domain already has a v=spf1 line, merge ours into it. Two SPF records make both invalid.

• DKIM must be one unbroken line. Use the copy button; manual retyping truncates it.

Incoming mail follows the MX record only. On Namecheap it lives under Mail Settings → Custom MX, not with the other host records, which is a very common miss.

The decryption key is stored per browser. On a new device, or after signing out, or after using Lock this device, enter your passphrase once to rebuild it locally.

Encrypted mail cannot be recovered, by us or by anyone. You can keep using the account, but the existing ciphertext stays unreadable. This is the deliberate cost of zero-access encryption.