Multi-record and email records

POST /api/v1/sessions has always taken records as an array, and the guided-manual and Cloudflare one-click paths have always written and verified every record in it. What changed in September 2026 is the Domain Connect one-click path: it used to express exactly one record, and now applies whole record sets — provided the set matches one of the templates DoDomain publishes. This page is the honest map of what each path does with a multi-record session, and how email records are verified.

The shapes that get one-click on Domain Connect

Domain Connect providers apply pre-approved templates, never arbitrary record lists. DoDomain publishes five (the JSON lives in docs/domain-connect/templates); a session gets the one-click button when its records — in any order, every one of them — fill exactly one template:

A session that matches none of them still works — it takes the guided-manual path (every provider) or Cloudflare one-click (Cloudflare zones), both of which handle any combination of the five record types.

What each connect path does with several records

Partial progress is reported honestly: after a check, the hosted page shows 2/3 found and marks exactly which record is still missing, with what is actually published at that name when something is there but does not match.

Email records: how verification reads them

Ownership tokens are compared byte for byte, case-sensitively — the whole point of a token. Email policies are not tokens, and comparing them byte for byte would fail the healthy outcome. Verification therefore reads the three email record types by their meaning:

• SPF (TXT at @, v=spf1 …). A zone may hold only one SPF record — two of them is a permanent error that fails every sender (RFC 7208 §3.2). So the correct result of "add include:_spf.yourproduct.com" is the zone's existing SPF record now containing that mechanism, which is exactly what Domain Connect's SPFM merge does and what a user does by hand. Verification passes when every mechanism your session asked for is present in the published v=spf1 record; the terminal ~all/-all is the zone owner's choice and is not compared. When an SPF record exists but lacks your mechanism, the hosted page says so and tells the user to edit that record rather than add a second one. The page also warns when the published record makes more than 10 DNS lookups on its own terms (the RFC 7208 evaluation limit) — a warning beside a found record, never a verification failure.
• DKIM (CNAME or TXT at <selector>._domainkey). A CNAME is compared like any hostname. A key TXT is compared tag by tag: v and k fall back to their RFC 6376 defaults when the provider omits them, and the key in p= is compared with whitespace removed, because long keys come back split across strings.
• DMARC (TXT at _dmarc). Compared tag by tag: the published record must be v=DMARC1 and carry every tag your session asked for with the same value (p=, rua=, and so on); report addresses are compared as sets. Extra tags the zone owner adds are not a mismatch. A _dmarc record with a different policy is reported as a different value — waiting will not change it.

Request them the way you would document them for a customer:

{
  "domain": "acme.com",
  "records": [
    { "type": "TXT", "host": "@", "value": "v=spf1 include:_spf.yourproduct.com ~all" },
    { "type": "CNAME", "host": "yp1._domainkey", "value": "yp1.dkim.yourproduct.com" },
    {
      "type": "TXT",
      "host": "_dmarc",
      "value": "v=DMARC1; p=none; rua=mailto:[email protected]"
    }
  ]
}

Constraints worth designing around

• One include: per SPF session. The Domain Connect template merges exactly one mechanism, so a session whose SPF value carries more (ip4:, a, a second include:) is entered by hand. Keep your SPF footprint to a single include host you control.
• One DKIM selector per session. Providers that rotate between two or three selectors (Microsoft 365, Amazon SES) need one session per selector for one-click, or the manual path for all of them at once.
• Byte-exact prefixes. For one-click, a DKIM TXT must start with v=DKIM1; and a DMARC TXT with v=DMARC1; (with the space) — the template fixes that prefix and appends the rest. Other spellings still work on the manual and Cloudflare paths.
• The ownership TXT sits under the host for custom-subdomain-cname-with-verification: host: "_dodomain-challenge" on a session for app.acme.com verifies at _dodomain-challenge.app.acme.com. An ownership TXT at the zone apex pairs with domain-verification on its own.
• Apex sessions never get a CNAME. apex-a-with-verification writes A/AAAA; Cloudflare's Domain Connect implementation rejects the APEXCNAME record type outright, and the Cloudflare one-click (OAuth) path remains the more capable option on Cloudflare zones.

Nothing about the API shape changed for any of this: records[] is the same array it always was, and the SDKs are untouched.