Skip to content
BurnerByte
Deploy

DNS records

Two records decide whether BurnerByte will accept mail for a domain. Four more decide whether the rest of the internet believes what you send. The formats are in the reference; this is the judgement around them.

The record formats — MX, TXT, SPF, DKIM, DMARC — are all in DNS Setup, with copyable examples. Follow that for the zone file. Read this for the decisions it does not make for you.

Throughout, example.com is the domain that will host inboxes and mail.yourserver.com is the hostname of the machine running the SMTP daemon. They are usually different names, and conflating them is the single most common reason a domain never verifies.

What gates what

Worth being precise about, because people spend evenings on records that gate nothing.

RecordStops mail arriving?
MXYes. Must resolve, and its target must match your configured SMTP hostname exactly.
TXTYes. Must contain the domain’s verification token.
SPFNo. Checked and shown on the domain page, but it gates nothing. A red SPF indicator does not stop a single message arriving.
DKIM, DMARC, PTRNo. These affect what you send, and how much of it lands.
If your instance only receives, MX and TXT are the whole job
Which is the common case for disposable inboxes. Route the handful of outbound messages — invites, password resets — through a relay that already has its reputation sorted, and none of SPF, DKIM, DMARC or PTR is your problem.

The exact-match rule

The MX target is compared to BB_SMTP_HOSTNAME case-insensitively with the trailing dot stripped — and that is the entire comparison. No suffix match, no subdomain fallback.

  • An MX of mail.yourserver.com against a configured hostname of yourserver.com will never verify.
  • Neither will anything against the localhost default, which is what you get if the variable is unset.
The API runs the check, not the SMTP daemon
Verification compares your MX record against BB_SMTP_HOSTNAME as the API process sees it. Setting it only on smtpd — which looks like the obvious place — leaves the API on its default, and then no domain can ever verify no matter how correct your DNS is. Set it on both.

The SPF indicator has its own surprise: it is satisfied only by a v=spf1 record containing your configured hostname as a literal substring. A mechanism like mx that merely resolves to your host does not count, so a perfectly valid "v=spf1 mx -all" leaves the indicator red forever. It gates nothing, so this is cosmetic — but it costs people an evening.

Use a subdomain, not your apex

Pointing your apex domain’s MX at a disposable-inbox platform routes every address at your organization there. It is easy to do by accident and unpleasant to undo, because the mail you lose in the meantime is gone.

Put the inboxes on test.example.com and leave example.com pointing wherever it already points. Addresses then read qa-signup-flow@test.example.com, which is also clearer to whoever reads the bug report, and each subdomain is added and verified in BurnerByte as its own domain. The zone records for that split are in DNS Setup.

On Cloudflare DNS

A common host for these zones, with three behaviours that will cost you an evening if you do not know them.

  • The proxy must be off for mail records. The orange cloud proxies HTTP and HTTPS only. An A record for mail.yourserver.com left proxied resolves to a Cloudflare address that does not speak SMTP, and delivery fails. Set it to DNS only — grey cloud.
  • MX records cannot point at a proxied name. Cloudflare warns you about this; the warning is correct.
  • Email Routing takes the zone over. It adds its own MX records. Turn it off on any domain BurnerByte is handling.

The web UI is a different matter — proxying that is fine and often desirable. See the Tunnel guide.

Reverse DNS and sending

If your instance sends as well as receives, the sending IP needs a PTR record resolving to the same hostname the A record points at. Receivers check it, and its absence is one of the strongest spam signals there is.

bash
$ dig +short -x 203.0.113.10mail.yourserver.com.

PTR is set by whoever owns the IP — your VPS provider’s control panel, not your DNS provider. Residential connections cannot set one, which is why mail sent from home is rejected almost universally. Receiving is unaffected.

Proving it works

bash
# Query a public resolver, not your own cache.$ dig @1.1.1.1 MX example.com$ dig @1.1.1.1 TXT example.com # Is the daemon actually reachable?$ nc -vz mail.yourserver.com 25 # End to end. Create an inbox in the UI first, then send to that address.$ swaks --to qa-signup-flow@test.example.com --server mail.yourserver.com:25

A 550 means the daemon is reachable and rejected the recipient — correct behaviour when no active inbox exists at that address. A timeout means the port is closed somewhere between you and it.

A failed lookup does not un-verify you
A timeout, SERVFAIL or resolver outage never downgrades an already-verified record. The flip side: a record you deleted stays green until a lookup succeeds and returns no match. The exception is the automatic check right after adding a domain, which has no previous value to keep.

Troubleshooting

SymptomCause
MX stays unverifiedThe target does not match BB_SMTP_HOSTNAME exactly, or that variable is set on smtpd but not on the API.
TXT stays unverifiedWrong token — re-adding a domain mints a new one — or the record is on the wrong name. It belongs on test.example.com, not _burnerbyte.test.example.com.
SPF indicator red, everything else fineExpected, if your record uses mx rather than naming the host literally. It gates nothing.
Verified, but no mail arrivesDNS is done; the problem is the network path. Check port 25 from outside, then the daemon logs.
Mail arrives, your senders get bouncesSPF, DKIM or DMARC. Read the bounce; it names the check.
Worked, then stoppedA registrar changed nameservers, or a Cloudflare proxy toggle turned orange.

Full record formats and the verification flow: DNS Setup. What happens to a message once it arrives: the SMTP pipeline.