Documentation/Using MailFlat/Custom Domains (BYOD)

Custom Domains (BYOD)

Connect a domain you own to receive and send emails using custom branding (Team plan).

What you get

Open inboxes like support@yourdomain.com. Incoming mail lands in MailFlat; outgoing mail is signed with your domain's own DKIM, so it passes SPF/DKIM/DMARC and shows up as coming from your brand, not from mailflat.net.

Four steps, then the domain behaves exactly like a MailFlat one.

Setup

Add the domain
Domains → type yourdomain.com → Add domain. You get five DNS records.
Add the DNS records
At your DNS provider. Read the provider notes below first. That is where nearly every failed setup goes wrong.
Verify
Wait a few minutes for DNS to propagate, then click Verify. The badge turns green.
Open an inbox on it
New inbox → pick your domain from the dropdown → support@yourdomain.com.

The five records

Type	Host	Purpose
TXT	_mailflat-verify	Proves you own the domain (required to verify)
MX	@	Routes incoming mail to MailFlat (mail.mailflat.net, priority 10)
TXT	@	SPF, authorizes MailFlat to send for you
TXT	mail._domainkey	DKIM, signs your outgoing mail
TXT	_dmarc	DMARC policy

Provider notes, read before pasting

These gotchas cause almost every failed verification

Nothing here is MailFlat-specific. It is how each registrar's DNS editor behaves. There is a step-by-step page for each one under DNS provider guides: Cloudflare, Hetzner, Namecheap, GoDaddy, Route 53, Porkbun, Vercel, IONOS, Squarespace, Gandi, Hostinger.

Hetzner, Namecheap, GoDaddy, name.com: the Host fieldEnter the name only, without your domain

Their Host / Name field wants only the left-hand part: type _mailflat-verify, not _mailflat-verify.yourdomain.com, because they append the domain automatically. Typing the full name gives you _mailflat-verify.yourdomain.com.yourdomain.com, which never verifies no matter how long you wait. This is the dashboard's default view. Keep the Provider dropdown on name only and paste the Host with its copy button.

Hetzner: keep the trailing dot on MXOtherwise your domain gets appended to the target

The MX value is mail.mailflat.net., and the final dot matters. Without it, Hetzner stores mail.mailflat.net.yourdomain.com and mail never reaches us, with no error shown anywhere. Cloudflare adds the dot for you; Hetzner does not.

Cloudflare, Route 53: paste the full nameThey accept (and normalise) the full name

Switch the Provider dropdown to full name and paste as shown. Cloudflare also tolerates the full name in panels that would otherwise double it, which is exactly why this mistake stays invisible until you move to a stricter provider.

MX on Namecheap lives somewhere elseMail Settings → Custom MX

It is not in the normal Host Records list. Switch the Mail Settings dropdown to Custom MX first, then add the record there.

One SPF record per domainMerge, never add a second

If your domain already has a v=spf1… record, whether from email forwarding or another sender, replace it with a merged one. Two SPF records make both invalid.

DKIM is long, do not retype itPaste on one line with the copy button

Use the copy button next to the record so nothing is truncated, and make sure your provider does not wrap it across lines.

Use it from your code

curl

# open an inbox on your domain (domain_id from GET /api/domains)
curl -X POST https://mailflat.net/api/inboxes \
  -H "Authorization: Bearer <token>" \
  -d '{ "prefix": "support", "domain_id": 1 }'
  # → support@yourdomain.com
# send from your domain, signed with your DKIM
curl -X POST https://mailflat.net/api/inboxes/support@yourdomain.com/send \
  -H "Authorization: Bearer <token>" \
  -d '{ "to": "user@gmail.com", "subject": "Your code", "body": "123456" }'
# read incoming mail (OTP auto-extracted), same as any inbox
curl https://mailflat.net/api/inboxes/support@yourdomain.com/emails/latest \
  -H "Authorization: Bearer <token>"