Koltrix logoKoltrixDocs
Send

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.

  1. Press it. You go to your DNS provider and sign in there, as usual.
  2. The provider shows the records Koltrix is asking for. Approve them.
  3. 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.

  1. 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.
  2. Under Zone Resources, choose Include → Specific zone → your domain. This way the token can't touch any other domain.
  3. Press Continue to summary, then Create Token, and copy the token.
  4. 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.com rather 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 doesTypeNameValue
1Proves you own the domainTXT_koltrixkoltrix-verify=<your token>
2Delivers your mail to KoltrixMX@mail.koltrix.com, priority 10
3Lets Koltrix send for youTXT@v=spf1 include:_spf.koltrix.com -all
4Signs your mail so it isn't spoofedTXTkx1._domainkeyv=DKIM1; k=rsa; p=<your key>
5Tells receivers what to do with fakesTXT_dmarcv=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.com added before its all term and everything else kept. Replace your existing record with it; don't add a second one. For example,

    v=spf1 include:_spf.google.com ~all

    becomes

    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=DMARC1 record passes, and you should have only one.
  • p=none passes too, with a note: it enforces nothing, and sender logos (BIMI) need p=quarantine or p=reject.
  • p=reject is 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.

ProviderName for the domain itselfName for the othersNotes
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 nameGoDaddy adds the domain itself. Typing the whole name gives you kx1._domainkey.example.com.example.com.
Namecheap@the short nameUnder Advanced DNS. To add the MX record, set Mail Settings to Custom MX first.
Amazon Route 53leave blankthe short namePut 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 blankthe short name, or the whole name if it asks for oneIf 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:

StatusMeaning
VerifiedFound, with the right value.
WaitingNot found yet. DNS can take a few minutes, sometimes a few hours.
ProblemFound, but not right. The card says what was found instead, and what to change.
RecommendedNot 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.