Skip to content

Templates

Templates

A template is a JSON document that names your service and lists the records it needs. It is published in the public Domain Connect Templates repository, where it is reviewed, and DNS providers onboard it from there. Keep the same file in your application and load it with Template::fromJson(), so the template you build URLs and check records with is the one you published.

{
  "providerId": "example.com",
  "providerName": "Example",
  "serviceId": "mail",
  "serviceName": "Example mail",
  "version": 1,
  "syncPubKeyDomain": "example.com",
  "syncRedirectDomain": "app.example.com",
  "records": [
    { "groupId": "sending", "type": "MX",   "host": "send", "pointsTo": "%mx%", "priority": 10, "ttl": 3600 },
    { "groupId": "sending", "type": "SPFM", "host": "send", "spfRules": "include:mail.example.com" },
    { "groupId": "sending", "type": "TXT",  "host": "ex._domainkey", "data": "p=%dkim%", "ttl": 3600, "txtConflictMatchingMode": "All" },
    { "groupId": "dmarc",   "type": "TXT",  "host": "_dmarc", "data": "v=DMARC1; p=quarantine", "ttl": 3600,
      "txtConflictMatchingMode": "Prefix", "txtConflictMatchingPrefix": "v=DMARC1", "essential": "OnApply" }
  ]
}

The model

Template holds providerId, providerName, serviceId, serviceName, version, records, and the optional syncPubKeyDomain, syncRedirectDomain, syncBlock, logoUrl, description and variableDescription. Template::fromJson() / fromArray() read it, toArray() writes it back; a missing or wrongly typed field, or an unknown record type, throws InvalidTemplate.

TemplateRecord holds one record: type (TemplateRecordType: A, AAAA, CNAME, NS, TXT, MX, SRV, SPFM, APEXCNAME), host, and the value field for its type — data for TXT, spfRules for SPFM, pointsTo for the rest — plus ttl, priority, groupId, essential (Always or OnApply), txtConflictMatchingMode (None, All, Prefix) and txtConflictMatchingPrefix. SPFM and APEXCNAME are Domain Connect pseudo-types: SPFM merges SPF terms into the zone's one SPF record, APEXCNAME is a CNAME-like record at the apex.

essential and the TXT conflict fields tell the DNS provider how to apply the record. They are kept on the model, but the record check below does not use them.

Hosts

A record's host is relative to the zone the template is applied to — the apex, or host.apex when the request has a host:

host Applied to acme.com Applied to mail.acme.com
@ or empty acme.com mail.acme.com
send send.acme.com send.mail.acme.com
ex.other.com. (trailing dot) ex.other.com ex.other.com

A trailing dot makes the host absolute; it is used as written. An APEXCNAME record always lands on @. Names are lowercased and carry no trailing dot.

Variables

A value written %name% is a variable ([A-Za-z0-9_]). Three are built in and filled from the zone, never by you:

Variable Value for mail.acme.com
%domain% acme.com
%host% mail
%fqdn% mail.acme.com

Every other variable must be supplied by the caller. Template::variables() lists them in order of first use, without the built-ins; that is the list applyUrl() requires values for. Variables may appear in host, pointsTo, data and spfRules. A substituted value is never scanned again, so a value that itself contains %...% is inserted as is.

Groups

groupId splits a template into parts the customer can apply separately — in the example, sending always and dmarc only when the domain has no DMARC policy yet. Template::groupIds() lists them. Pass group ids on ApplyRequest (sent as groupId=sending,dmarc) and to recordSet(); an id the template does not define is refused. An empty list means every record. With a non-empty list, a record without a groupId is left out.

The record set

DomainConnect::recordSet(Template $template, Zone $zone, array $variables, array $groupIds = []): RecordSet (or RecordSet::fromTemplate()) expands a template into the records the zone should carry once applied: a list of ExpectedRecord (type, name, value, priority, ttl, groupId), with every variable substituted and every name fully qualified. CNAME, NS, MX and APEXCNAME targets are lowercased and lose their trailing dot; for SPFM the value is the SPF terms.

Use it for anything that needs "the records for this customer": a table of records to add by hand when the DNS provider does not support Domain Connect, and the check below.

It throws InvalidApplyRequest for an unknown variable, an unknown group, a variable a kept record needs but was not given, a record missing its value field, and any SRV record (not supported).

Checking the records

DomainConnect::check(RecordSet $set): Report runs RecordSetCheck through the diagnostics engine. It reads each expected record from the zone's authoritative nameservers and returns the usual Report with one Finding per record, in record-set order, category DomainConnect:

Check id Severity When
domain-connect.present info A live record matches.
domain-connect.missing error No record of that type at the name, or the lookup failed.
domain-connect.mismatch error Records exist but none matches.

Each finding's context carries name, type, expected and the live values. One matching record among several is enough. TTLs are not compared.

Type Looked up as Matches when
A, AAAA A, AAAA The address string is equal.
CNAME, NS CNAME, NS The target is equal, ignoring case and a trailing dot.
APEXCNAME CNAME at the apex As CNAME. A provider that flattens the apex CNAME into addresses will show it as missing.
MX MX Priority and target (case and trailing dot ignored) are equal.
TXT TXT The value is equal after trimming; multi-string TXT records are joined first.
SPFM TXT A record starts with v=spf1 and contains every whitespace-separated term of spfRules as an exact term. v=spf1 include:mail.example.com ~all matches include:mail.example.com; include:mail.example.com.evil does not.

check() only tells you what DNS says right now. A DNS provider's "success" redirect can come before the records are served, so check again later rather than treating a first missing as failure.