Install and operate
DNS setup
Ten records. Five are required; the rest make things work properly. This page covers what each one does, what happens without it, and how to verify it.
| Record | Host | Purpose | Required |
|---|---|---|---|
| TXT | @ |
Ownership verification | Yes |
| TXT | @ |
SPF — which servers may send as you | Yes |
| TXT | _dmarc |
DMARC — what to do when SPF and DKIM fail | Yes |
| CNAME | corsair-1._domainkey |
DKIM signing key | Yes |
| CNAME | corsair-2._domainkey |
Spare DKIM key, for rotation | No |
| CNAME | corsair-3._domainkey |
Spare DKIM key, for rotation | No |
| CNAME | mta-sts |
MTA-STS policy host | No |
| CNAME | autoconfig |
Thunderbird automatic setup | No |
| CNAME | autodiscover |
Outlook automatic setup | No |
| MX | @ |
Where your mail is delivered | Yes |
The panel generates all of them with the values for your installation, and marks which are required. Only the first DKIM selector has to exist — a domain should not sit unverified because someone added one CNAME.
This page explains them; it is not a substitute for the values on the DNS Setup tab, which are the ones to publish.
Verification#
A TXT record containing a token unique to your domain.
It proves you control the domain before Corsair routes mail for it. Without that check, anyone could add someone else's domain and start receiving their mail.
Keep it published. Removing it after verification means the domain fails its next periodic re-check.
SPF#
v=spf1 include:spf.example-host.com -allLists which servers may send as your domain. -all means "and nobody else".
The include: value is whatever the operator set as MAIL_SPF_HOST. The check is by prefix rather than exact match, so you can add other senders:
v=spf1 include:spf.example-host.com include:_spf.google.com -allThere must be exactly one v=spf1 record. Two is a permanent error. This happens constantly when a domain is migrated and the old record is left behind.
-all versus ~all: -all is a hard fail, ~all a soft one. Start with ~all if you are unsure whether you have listed every sender, and tighten to -all once you are.
DKIM#
Published as a CNAME, not a TXT record.
A 2048-bit key does not fit in a single TXT string, half the DNS control panels in the world mangle the chunked form, and a CNAME lets the key rotate on the server without you touching DNS again.
corsair-1._domainkey.example.com. CNAME dkim-1.mail.example.com.Corsair answers the lookup at the target and serves the current public key.
Three selectors are created per domain. Only the first has to exist; the others are there so a rotation is a flag flip rather than a support ticket. See Domains for the rotation order that avoids a gap.
Check what a receiver sees:
dig +short CNAME corsair-1._domainkey.example.com
dig +short TXT corsair-1._domainkey.example.comThe TXT lookup should follow the CNAME and return v=DKIM1; k=rsa; p=….
Key rotation#
Customers publish the CNAMEs once and never touch them again. You publish the key itself: the three MAIL_DKIM_HOSTS names are in your zone, each holds one TXT record, and Corsair has no credentials for your zone (the DNS tokens it is handed are for customers' zones and are never stored). A host holds one key, so a rotation moves signing to a different selector, which is why all three CNAMEs should be published. Domains created before this existed may only have the first; they keep their current key until their next selector resolves, and nothing breaks.
Each host moves through these phases:
| Phase | Meaning |
|---|---|
spare |
Idle. Not signing, nothing to publish |
staged |
A new key exists. You publish its TXT record |
published |
Seen in DNS. Waits DKIM_SOAK_HOURS (48) so resolver caches expire |
active |
Signing. Each domain moves only when its own corsair-N._domainkey name resolves to this key |
retiring |
Replaced, but still published for DKIM_RETIRE_DAYS (7) so in-flight mail verifies |
revoked |
Publish v=DKIM1; k=rsa; p= (empty), which tells verifiers the key is withdrawn |
bun run dkim status # every host, its phase, and exactly which TXT to publish where
bun run dkim rotate # start now: stage a new key on the next host
bun run dkim advance # run the worker's pass immediatelystatus prints lines such as publish at dkim-2.mail.example.com: TXT "v=DKIM1; k=rsa; p=…", already split into 255-character strings for DNS panels that need it. Publish it, and the worker (hourly) does the rest. Set DKIM_ROTATE_DAYS to start cycles automatically; the default 0 never starts one, so an operator who publishes by hand is not surprised. A cycle started with rotate is advanced either way.
Corsair never switches signing to a key it has not seen resolve. A host whose TXT does not match stays staged; a domain whose own selector does not resolve to the new key keeps signing with the old one, and the old host is not revoked while any domain still signs with it. status lists those domains. Activating a key by hand from the panel is held to the same check.
DMARC#
v=DMARC1; p=quarantine; rua=mailto:[email protected];Tells receivers what to do when a message claiming to be from you passes neither an aligned SPF nor an aligned DKIM check.
| Policy | Effect |
|---|---|
p=none |
Do nothing. Monitoring only |
p=quarantine |
Treat as suspicious — usually the spam folder |
p=reject |
Refuse it outright |
quarantine is the sensible default. Move to reject once you are confident every legitimate sender for the domain is covered — including the marketing platform, the ticketing system, and whatever else sends as you.
rua= gives you aggregate reports, which is how you find the sender you forgot. Add it before tightening the policy, not after.
The generated record points rua at dmarc-reports@ on the domain itself. That address needs no mailbox: Corsair accepts mail for it, reads the reports (gzip, zip, or plain XML), and files them under the domain, where Reports in the control panel totals them by sending IP and by reporting organisation. If you do create a mailbox or alias called dmarc-reports, it receives the messages as well — the parse is in addition to delivery, not instead of it.
Two rules decide what is filed:
- A report must be about the domain it was sent to, or a subdomain of it. A report mailed to
[email protected]aboutb.exampleis dropped, so one domain cannot fill another's dashboard. - The sender must authenticate — SPF or DKIM passed. Every large reporter signs its reports; without the check anyone could invent traffic by mailing an XML file.
You can keep your own rua instead, or as well (rua=mailto:[email protected],mailto:[email protected]). A destination on another domain has to publish a TXT record authorising it — example.com._report._dmarc.dmarc-service.example with v=DMARC1 — or receivers will not send to it. Commercial report services publish theirs for you.
**DMARC passes if either SPF or DKIM passes and aligns with the From domain.** One is enough by design — that is what makes forwarding survivable, since forwarding breaks SPF but preserves DKIM.
MX#
example.com. MX 10 mail.example.com.Where mail for the domain is delivered.
Remove the old provider's MX records entirely. Leaving them at a worse priority means the old host keeps receiving whenever yours is briefly unreachable, which is the opposite of a clean cutover.
Two MX records at equal priority is how you run two mail hosts — senders pick one and retry the other on failure.
MTA-STS#
Tells senders to require TLS when delivering to you, and to refuse to fall back to plaintext if it fails.
Corsair serves the policy at /.well-known/mta-sts.txt. The mode reflects whether the MX can actually offer STARTTLS — on a runtime where it cannot, the policy is published as none rather than claiming a capability that is not there. See Deliverability.
version: STSv1
mode: none
mx: mail.example.com
max_age: 604800Corsair generates the mta-sts CNAME. The _mta-sts TXT record carrying the policy id is not generated for you — MTA-STS requires one, and senders will not notice a policy change without it, so add it by hand if you are using MTA-STS seriously:
_mta-sts.example.com. TXT "v=STSv1; id=20260810000000"Bump the id whenever the policy changes.
TLS reporting#
_smtp._tls.example.com. TXT "v=TLSRPTv1; rua=mailto:[email protected]"Optional. Asks senders for a daily report (RFC 8460) of how their TLS sessions to your MX went — how many negotiated TLS, and why any did not. It is the feedback loop that makes MTA-STS safe to tighten: an expired certificate shows up as certificate-expired failures before it becomes lost mail.
Like dmarc-reports@, the tlsrpt@ address needs no mailbox; Corsair files the JSON reports under the domain and shows them beside the DMARC ones. Entries in a report about any other domain are dropped.
autoconfig and autodiscover#
CNAMEs that let Thunderbird and Outlook configure themselves from an email address alone. Optional, and worth publishing — the alternative is telling every user six hostnames.
For contacts, a client that starts from an email address looks for a _carddavs._tcp SRV record on the domain (RFC 6764). Publish one only if the bare domain is not served by Corsair; the records are in Contacts (CardDAV).
Checking everything#
dig +short MX example.com
dig +short TXT example.com
dig +short TXT _dmarc.example.com
dig +short CNAME corsair-1._domainkey.example.com
dig +short TXT corsair-1._domainkey.example.comThe panel's DNS Setup tab does this for you and, when a record does not match, shows what it actually observed. That is usually enough to spot the problem immediately.
When a record will not verify#
The provider appended the domain. You entered _dmarc.example.com into a field that already appends the zone, giving _dmarc.example.com.example.com. Enter just _dmarc.
Quotes were stored literally. Some panels want the value without quotes and store them if you paste them. "v=spf1 …" with the quotes in the value is not a valid SPF record.
Two SPF records. Exactly one.
It has not propagated. A record can take up to the previous record's TTL to become visible. If you lowered the TTL only when you made the change, you are waiting for the old one.
Proxying is on. Cloudflare's orange cloud on a _domainkey record breaks it.
Before a migration, lower your TTLs#
A day before you plan to change the MX, drop its TTL to 300 seconds. Then the cutover window is five minutes rather than however long the old TTL was.
Raise them again afterwards.