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.

429 comes from the sign-in, sign-up and OTP endpoints, which are throttled per IP. The agent API has no per-hour request quota: your plan caps emails, not API calls.

What can bite instead is a loop that keeps failing. Many failing requests from one IP in a short window look like scanning and get the address blocked at the network level for two hours, and you see a refused connection, not a 429. Polling an inbox you own is not the risk; a script retrying a rejected payload forever is. Give every wait a deadline, and stop on the first error instead of retrying blind.

Google Calendar decides on its own when to check a subscribed link, usually every 8 to 24 hours, and there is no refresh button. Apple Calendar and Outlook check much more often. Nothing is wrong with the link: the Calendar tab and the API always show the current state. If you need a change to reach people now, rely on the invitation email, which updates their calendar right away.

To see your own meetings without the wait, turn on Put these meetings on your own calendar in the Calendar tab. Each meeting is then also sent to your sign-in address as an invitation, so it lands in your calendar within a minute, together with your guests' answers.

Google reads a subscribed link once when you add it, then again on its own schedule. If the calendar was empty at that moment, Google keeps showing an empty calendar until its next check, which can take up to a day. The Calendar tab tells you when this is the case: it shows which calendar app last checked the link and warns when your latest changes are newer than that check.

To see the meeting now, press New link, then Add to Google Calendar again, and remove the old calendar in Google. A new link counts as a new calendar, so Google reads it right away. Apple Calendar and Outlook catch up by themselves within minutes.

• Give it a few minutes. Outlook and Apple answer within minutes. Gmail usually does too, but now and then its reply arrives much later.

• Apple sends only the first answer. If a guest changes their mind in Apple Calendar, no new reply is sent. Gmail and Outlook send one each time.

• The answer must come from the guest’s own mail provider. Replies that are not signed by it (DKIM) stay in the inbox as mail but do not change the calendar, so nobody can answer for someone else.

iPhone Mail does not show answer buttons for invitations from outside your own accounts. Tap the invitation to open it in the Calendar app and answer there, or answer from Gmail, Outlook or a Mac.

On the Free plan without a verified domain, the inbox can only send to your own addresses, and a meeting invitation is a normal email. Upgrade, or verify a domain you own, to invite anyone.

An encrypted inbox never lets us read mail content, so we cannot read an invitation either. Use a plain inbox or an agent inbox for meetings. Agent and test inboxes are always plain text.

When several meetings share a title, check the date and the badge before you answer. Cancelled meetings move to the end of Upcoming and cannot be answered. When testing, give each meeting its own title.

• 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.