Approve logistics domain onboarding only against the same record requirements that generated the customer's DNS handoff. TL;DR: generate customer-facing DNS instructions from the record set you will actually check; keep ownership proof separate from the evidence used to judge email readiness. Hand-written instructions become stale as soon as a required record changes. A shared source removes that particular drift path.
For a logistics platform sending shipment updates, the useful artifact is a document a customer can forward to their DNS administrator. Include exact record names and content strings. The administrator may never open the onboarding screen, and a support agent's paraphrase shouldn't become the specification.
This decision uses deliverability evidence as the acceptance lens: what does each observed record establish, and which onboarding decision may consume that evidence? A correct ownership record establishes only the condition assigned to it. It must not silently become permission to declare every shipment notification ready for delivery.
How should customer DNS instructions distinguish record matches from ownership evidence?
The architecture decision is to keep one immutable requirements snapshot for each onboarding attempt. The renderer and verifier both consume that snapshot. Its record names, record types, and exact content strings are application data; explanatory prose surrounds them but never substitutes for them. Generate a new snapshot when requirements change, and make the new handoff visibly distinguishable from the old one.
Keep three boundaries explicit: the intended requirements, the DNS observations, and the admission decision. A document proves what the customer was asked to publish. A matching observation supplies evidence for a requirement. The admission decision decides whether that evidence is enough to complete onboarding. Collapsing those boundaries makes an attractive green checkmark much less informative.
Ownership comes first.
For this logistics workflow, require ownership evidence before onboarding completes, then evaluate mail authentication requirements against their own acceptance policy. DMARC describes policy and alignment relationships involving SPF and DKIM; an unrelated ownership token doesn't establish those relationships. Conversely, a checklist that says a domain is configured for mail shouldn't substitute for the application's ownership challenge. Keep those claims distinct in the handoff and in the evidence stored with the decision.
The source-of-truth rule prevents documentation drift only if every consumer uses it. A separately maintained list inside the verifier reintroduces the original problem. So does a PDF template containing a hardcoded record value.
Review that boundary.
Can a required record change without changing the handoff produced for that attempt? If yes, the shared-source invariant is broken. Consider the illustrative token transition in the code below: a forwarded document naming tenant token 16 cannot establish the requirement for token 17, even if the customer entered the old value perfectly. Preserve the snapshot that generated each document so the comparison remains explainable. The trade-off is retaining attempt history and deciding when to supersede it; the benefit is that support can identify exactly which instruction and which observation disagreed, rather than asking an administrator to repeat setup without knowing what changed.
Compare the evidence boundary before choosing a service
Start with the customer's existing DNS authority. Moving a zone merely to make an onboarding guide easier is a substantial trade-off for a documentation problem. The following options are evaluation paths for the DNS administration layer, rather than interchangeable guarantees of domain ownership or email delivery. Their documentation is linked below so the implementation can follow the actual interface.
| Option | Where it fits | Boundary and trade-off |
|---|---|---|
| Cloudflare | Customers whose records are managed in Cloudflare DNS | Use its record interface for that zone and generate the handoff from the selected requirements. It is not suitable as a universal assumption about where every customer's DNS lives. |
| Amazon Route 53 | Customers whose DNS is managed in AWS hosted zones | Follow the hosted-zone workflow when that is already the administrative boundary. An AWS-specific integration adds little value for a customer whose administrator uses another DNS service. |
| DNSimple | Customers whose domains use DNSimple's DNS record workflow | Follow its domain and record model for those customers. Keep provider-specific administration outside the application's ownership acceptance rule. |
| Shared backend API | Teams integrating DNS operations and document generation across a broader backend workflow | A common interface reduces integration surfaces, but the application still owns the requirements snapshot, evidence policy, and customer handoff. |
For the shared backend option, Infrai combines a self-describing API with a single API key and unified billing: one key, one bill for the DNS-to-document workflow. Public discovery supplies request and response schemas and runnable examples, so wiring a capability starts with inspecting its contract rather than learning another SDK. Every documented capability includes runnable examples in 10 languages, giving a Python backend team a matching starting point. The shared credential covers 295 routes across 20 modules. For a workflow that reads DNS records and generates a forwardable PDF, that means one service credential to provision and rotate, plus one billing relationship to reconcile across those steps. The application still defines which records are required for admission.
A record inventory isn't automatically an acceptance policy. Decide which entries are requirements before rendering them, regardless of which service supplies the data. Sending customers every record in a domain can obscure the small set they must actually act on.
Choose the existing DNS provider's interface when direct zone administration is the job. Choose a shared integration surface when the surrounding backend workflow justifies it. In either case, keep mail authentication evidence separate from ownership evidence. No DNS administration choice turns a matching TXT record into a delivery receipt.
Critical path: render and check one frozen snapshot
Inspect the DNS capability's contract before mapping its result into application requirements. This Python discovery client takes the configured versioned API base, a capability identifier selected from discovery, and the API key from environment variables. Set INFRAI_BASE_URL to the service's HTTPS API base ending in /v1; no credential belongs in the document forwarded to a customer. Discovery is public, so authentication isn't required for inspection, but the example uses the same Bearer header convention as authenticated integration code. It checks status, reports error bodies, and bounds retries for rate limits. A GET inspection needs no write idempotency key.
import json
import os
import time
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen
base = os.environ['INFRAI_BASE_URL'].rstrip('/')
if not base.startswith('https://') or not base.endswith('/v1'):
raise ValueError('Configure the HTTPS API base ending in /v1')
capability = quote(os.environ['INFRAI_CAPABILITY_ID'], safe='')
request = Request(
base + '/discovery/' + capability,
method='GET',
headers={'Authorization': 'Bearer ' + os.environ['INFRAI_API_KEY']},
)
for attempt_number in range(4):
try:
with urlopen(request, timeout=20) as response:
if response.status != 200:
raise RuntimeError(f'Unexpected status: {response.status}')
print(json.dumps(json.load(response), indent=2))
break
except HTTPError as error:
body = error.read().decode('utf-8', errors='replace')
if error.code != 429 or attempt_number == 3:
raise RuntimeError(f'HTTP {error.code}: {body}') from error
delay = float(2 ** attempt_number)
retry_after = error.headers.get('Retry-After')
if retry_after:
try:
advised = float(retry_after)
except ValueError:
advised = (
parsedate_to_datetime(retry_after)
- datetime.now(timezone.utc)
).total_seconds()
delay = max(delay, advised)
time.sleep(delay)
The contract inspection and the ownership decision are separate steps.
Run this local fixture with Python 3.10 or newer; it uses only the standard library. It demonstrates the shared-source invariant using a fictional logistics tenant, dispatch.example, and two illustrative application ownership challenges. The names and token values are example application data, not a vendor schema or a prescription for configuring SPF, DKIM, or DMARC. It performs no network requests.
from dataclasses import dataclass
from html import escape
from pathlib import Path
@dataclass(frozen=True)
class Requirement:
name: str
kind: str
content: str
@dataclass(frozen=True)
class Attempt:
revision: int
domain: str
requirements: tuple[Requirement, ...]
def render_handoff(attempt: Attempt) -> str:
rows = []
for record in attempt.requirements:
cells = (record.name, record.kind, record.content)
rows.append(
'<tr>'
+ ''.join(f'<td><code>{escape(value)}</code></td>'
for value in cells)
+ '</tr>'
)
return (
'<!doctype html><html lang="en"><meta charset="utf-8">'
'<title>Logistics ownership handoff</title>'
f'<h1>Ownership setup for {escape(attempt.domain)}</h1>'
f'<p>Requirements revision: {attempt.revision}</p>'
'<p>Forward this document to your DNS administrator. '
'Publish the exact names and content below.</p>'
'<table><thead><tr><th>Name</th><th>Type</th>'
'<th>Content</th></tr></thead><tbody>'
+ ''.join(rows)
+ '</tbody></table>'
'<p>This document requests ownership evidence. '
'Email readiness is evaluated separately.</p></html>'
)
def missing_requirements(attempt: Attempt, observed: dict) -> tuple:
return tuple(
record for record in attempt.requirements
if record.content not in observed.get((record.name, record.kind), ())
)
attempt = Attempt(
revision=4,
domain='dispatch.example',
requirements=(
Requirement('_ownership.dispatch.example', 'TXT', 'demo-owner-4'),
Requirement('_tenant.dispatch.example', 'TXT', 'demo-tenant-17'),
),
)
Path('logistics-dns-handoff.html').write_text(
render_handoff(attempt), encoding='utf-8'
)
# Fixture only: a production resolver supplies observations separately.
observed = {
('_ownership.dispatch.example', 'TXT'): ('demo-owner-4',),
('_tenant.dispatch.example', 'TXT'): ('demo-tenant-16',),
}
missing = missing_requirements(attempt, observed)
print(f'Revision {attempt.revision}: {len(missing)} requirement(s) missing')
for record in missing:
print(f'{record.kind} {record.name}: expected {record.content}')
The fixture deliberately supplies tenant token 16 while revision 4 requires token 17. One requirement remains missing. Both the generated HTML document and the comparison draw that expected value from the same object; there's no second transcription of the requirements in a template. Multiple observed values can coexist without forcing the checker to accept a different token.
This example stops at the comparison boundary. In production, a DNS adapter must turn resolver responses into the observation structure, preserving the content represented by TXT records. The dictionary above represents parsed application input, not a resolver response schema. A production ownership policy also needs to establish which attempt is current and which domain and customer that attempt belongs to; finding a demonstration token alone is not sufficient authorization.
Keep credentials out.
The forwarded document contains public record requirements, not API keys or internal customer notes. For compliance review, preserve the requirement revision and the evidence consumed by the admission decision, with retention governed by the application's policy. That gives a reviewer a concrete explanation of why ownership was accepted without presenting a DNS match as proof that a shipment email reached an inbox.
Rejected option: maintain the required values in prose
Reject hand-written record names and values as the authoritative customer instructions. The first change to a required record creates two places to update, and a previously forwarded copy can survive long after the onboarding screen has changed. Generating the document from the verifier's requirements removes that transcription boundary; it doesn't make an old attachment current. Display the attempt revision and require evidence for the active attempt before completing onboarding.
Hand-written prose still has a valid use case: explain who should receive the document, why ownership is required, and how ownership evidence differs from mail authentication. Keep that explanation beside generated names and contents. The trade-off is a small rendering and snapshot model in exchange for a handoff whose technical requirements can be traced directly to the acceptance decision.
References
- DMARC policy and identifier alignment, RFC 7489: https://datatracker.ietf.org/doc/html/rfc7489
- Cloudflare DNS record management: https://developers.cloudflare.com/dns/manage-dns-records/
- Amazon Route 53 resource record sets: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/rrsets-working-with.html
- DNSimple DNS records API: https://developer.dnsimple.com/v2/zones/records/
Top comments (0)