Custom domains and DNS
To send and receive mail on your own domain, Koltrix needs five DNS records. Settings → Domains & addresses shows the exact values for your domain, each with a copy button and a live check; this page explains what they are and how to add them. It takes about ten minutes of work, then a wait for DNS (usually a few minutes, occasionally a few hours). If your DNS provider allows it, Koltrix can add the records for you instead.
Automatic setup
Open the domain in Settings → Domains & addresses (or the DNS step of onboarding). If one of these options is available for your domain, it appears above the records. The records stay below in every case, so you can always add them yourself.
Set up automatically with your DNS provider
If your DNS provider supports Domain Connect and has enabled Koltrix, you see a Set up automatically with <your provider> button.
- Press it. You go to your DNS provider and sign in there, as usual.
- The provider shows the records Koltrix is asking for. Approve them.
- You come straight back to Koltrix, which checks the records.
A few details:
- Koltrix only asks for the records that aren't right yet. A DMARC record
that already works stays as it is, even a stricter
p=reject. - An existing SPF record is merged by your provider, not duplicated.
- If the domain already receives mail elsewhere, your provider shows you which MX records the new one replaces before you approve.
- The link to your provider is signed by Koltrix, so nobody can use it to slip in different records.
The button appears on its own as DNS providers enable Koltrix. There is nothing to switch on.
Connect Cloudflare
If your domain's DNS is on Cloudflare and the button above isn't offered, you see Connect Cloudflare instead. You give Koltrix a Cloudflare API token that can edit this one domain's DNS, and Koltrix adds the records with it.
- Press Connect Cloudflare, then Open Cloudflare's token page. It opens Cloudflare's Create API token form with the right permissions already filled in: Zone · Read and DNS · Edit.
- Under Zone Resources, choose Include → Specific zone → your domain. This way the token can't touch any other domain.
- Press Continue to summary, then Create Token, and copy the token.
- Paste it into Koltrix and press Add the records.
Koltrix then:
- adds only what is missing, and leaves records that already match alone;
- edits your existing SPF record to include
include:_spf.koltrix.comrather than adding a second one; - keeps a DMARC record that already works;
- asks first if the domain already has other MX records, because replacing them moves your incoming mail to Koltrix;
- never deletes anything else.
It reports what it changed and runs the check straight away.
Koltrix uses the token once, for that request, and does not store or log it. You don't need it afterwards, so delete it in Cloudflare under My Profile → API Tokens.
The five records
| # | What it does | Type | Name | Value |
|---|---|---|---|---|
| 1 | Proves you own the domain | TXT | _koltrix | koltrix-verify=<your token> |
| 2 | Delivers your mail to Koltrix | MX | @ | mail.koltrix.com, priority 10 |
| 3 | Lets Koltrix send for you | TXT | @ | v=spf1 include:_spf.koltrix.com -all |
| 4 | Signs your mail so it isn't spoofed | TXT | kx1._domainkey | v=DKIM1; k=rsa; p=<your key> |
| 5 | Tells receivers what to do with fakes | TXT | _dmarc | v=DMARC1; p=quarantine |
@ means the domain itself. The token and the key are different for
every domain, so copy them from Settings → Domains & addresses rather than from
this page. The domain becomes verified, and mail starts to flow,
once all five check out.
1. Ownership
A TXT record at _koltrix holding a token made for this domain in this
workspace. It proves that whoever added the domain controls its DNS, so
nobody else can claim your domain in their workspace. Tokens are random
and never reused. Leave the record in place after the domain verifies.
2. MX
Points incoming mail for your domain at Koltrix. Name @, mail server
mail.koltrix.com, priority 10.
Publishing it moves your incoming mail to Koltrix, so do it when you are ready to switch. Remove any other MX records for the domain at the same time: mail goes to the lowest priority number that answers, and an old record left behind keeps receiving some of it.
3. SPF
A domain may have only one SPF record. Two v=spf1 records is an
error, and receivers then treat SPF as failed for all of them.
-
No SPF record yet? Add
v=spf1 include:_spf.koltrix.com -all. -
Already have one (for Google Workspace, a CRM, an invoicing tool)? Koltrix shows you a merged version: your record, with
include:_spf.koltrix.comadded before itsallterm and everything else kept. Replace your existing record with it; don't add a second one. For example,v=spf1 include:_spf.google.com ~allbecomes
v=spf1 include:_spf.google.com include:_spf.koltrix.com ~all
The check looks for the exact term include:_spf.koltrix.com. Domains
set up before it existed use include:koltrix.com, which is still
accepted. SPF allows ten DNS lookups per record and each include:
costs at least one, so a record with many providers in it can run out.
4. DKIM
Koltrix generates a 2048-bit key for each domain, used by that domain
alone, and signs every message on the mail server. You publish the
public half as a TXT record at kx1._domainkey.
The value is long: about 400 characters. Use the copy button rather than selecting it by hand, and paste it in one go.
A single TXT string holds at most 255 characters, so some DNS
providers split a long value into several quoted pieces when you save
it ("v=DKIM1; k=rsa; p=MIIB…" "…IDAQAB"). That is fine: receivers join
the pieces back together, and the check does too. What matters is that
no character is missing and nothing extra (a space, a line break) was
added in between.
5. DMARC
Tells receivers what to do with mail that claims to be from your domain
but fails SPF and DKIM. Koltrix suggests v=DMARC1; p=quarantine:
fakes go to spam.
- Already have a DMARC record? Keep it. Any valid
v=DMARC1record passes, and you should have only one. p=nonepasses too, with a note: it enforces nothing, and sender logos (BIMI) needp=quarantineorp=reject.p=rejectis the strongest setting: fakes are refused outright.
The suggested record has no rua= reporting address, because aggregate
reports are only useful if something reads them. If you use a DMARC
report service, add its rua= address to the record; Koltrix accepts
it either way.
Adding them at your DNS provider
Providers disagree about the Name field. Most add your domain to the
end for you, so you type only the part in front of it. Settings →
Domains shows both the short name and the whole name
(kx1._domainkey.example.com) with a copy button for each.
| Provider | Name for the domain itself | Name for the others | Notes |
|---|---|---|---|
| Cloudflare | @ | _koltrix, kx1._domainkey, _dmarc (without your domain) | The orange-cloud proxy only applies to A, AAAA and CNAME records, so it has nothing to do with these: TXT and MX are always DNS only. |
| GoDaddy | @ | the short name | GoDaddy adds the domain itself. Typing the whole name gives you kx1._domainkey.example.com.example.com. |
| Namecheap | @ | the short name | Under Advanced DNS. To add the MX record, set Mail Settings to Custom MX first. |
| Amazon Route 53 | leave blank | the short name | Put TXT values in double quotes. Route 53 refuses a string over 255 characters, so split the DKIM value into two quoted pieces in the same record: "first 255 characters" "the rest". |
| Anything else | @ or blank | the short name, or the whole name if it asks for one | If the saved record shows your domain twice, remove the second copy. |
Checking
Press Check again in Settings → Domains & addresses after you save the records. Each record shows where it stands:
| Status | Meaning |
|---|---|
| Verified | Found, with the right value. |
| Waiting | Not found yet. DNS can take a few minutes, sometimes a few hours. |
| Problem | Found, but not right. The card says what was found instead, and what to change. |
| Recommended | Not required: a new record for a domain that already works (see below). |
Nothing about a record you have not added yet is harmful. A domain that is waiting for DNS just doesn't send or receive until it verifies.
Upgrading an existing domain
Domains verified before these five records existed keep working exactly as they do today: they stay verified, mail keeps flowing, and outbound mail stays signed. Nothing is broken and there is no deadline.
Settings → Domains & addresses shows them as verified, with a Security upgrade banner listing only the records they don't have yet, usually:
- the ownership record at
_koltrix, and - the DKIM record at
kx1._domainkey, which gives the domain its own signing key instead of the shared one.
Add them when convenient and press Check again. As soon as the
kx1._domainkey record checks out, Koltrix starts signing the domain's
mail with its own key; you don't have to do anything else. Leave the
old koltrix._domainkey record in place: mail sent before the switch
was signed with it, and receivers may still check it. Your existing
include:koltrix.com SPF record keeps working; changing it to
include:_spf.koltrix.com is optional.
If the domain is claimed by another workspace
The same domain can be added to more than one workspace while it is waiting for DNS, so that someone who adds your domain first can't block you. Only one workspace can verify it: the first one whose own ownership token appears in DNS.
If Settings → Domains & addresses says Claimed elsewhere, the domain is verified in another workspace. If that is a workspace of yours, use the domain there. If the domain is yours but the workspace isn't, add this workspace's ownership record and check again, and contact support. If the domain isn't yours, remove it.
More fixes for a domain that won't verify are in Troubleshooting.