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 ConnectCopy Anchor Link

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 accepted record types (A, AAAA, CNAME, TXT, MX, SRV, CAA, and NS below the root). A session that includes SRV, CAA or NS is never offered Domain Connect one-click, since no template carries those types.

More templates are prepared for those sessions. No provider serves them yet, so today these sessions keep the paths above; the one-click button appears only where a provider serves the template a session needs. email-sending covers a full sending setup in one consent (SPF, up to three DKIM records, DMARC, and the MAIL FROM subdomain's MX and SPF), website covers up to four A and two AAAA addresses with www, a wildcard and the certificate challenge CNAME, and site-verification adds third-party ownership tokens (Google, Microsoft 365 and others). A universal template, dns-records, takes any other combination of the five record types; it is offered to DNS providers directly and is not in the public template registry.

What each connect path does with several recordsCopy Anchor Link

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 themCopy Anchor Link

Ownership tokens are compared byte for byte, case-sensitively; that is 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. One caveat for one-click applies: a provider's SPFM merge may rewrite that qualifier when it rebuilds the record (one provider has told us its merge always lands on ~all), so if your product depends on a strict -all, read the published record back rather than assuming it survived the merge. 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:dmarc@yourproduct.com"
    }
  ]
}

Constraints worth designing aroundCopy Anchor Link

• 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. The free SPF record checker parses a domain's record, walks its includes, and counts the DNS-querying terms against RFC 7208's limit of ten, worth running against a customer's domain before adding your include to it, since a record already at the limit will permerror the moment yours lands. The SPF 10-lookup limit lists what the includes common email vendors document actually cost, measured.
• 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.