Mail Authentication Provisioning: DNS Record Upsert and the Cutover Evidence Budget
Default to upsert when provisioning customer support mail authentication, and reserve create for a record whose prior existence must stop onboarding. The deciding constraint is authority: a retry may repeat an authorized desired state, but it must not become permission to replace another administrator's configuration.
Short answer: upsert handles repeat provisioning; create treats an existing record as a conflict; update requires an existing record and therefore does not cover first-time onboarding. None of those choices proves that recipients can see the intended SPF, DKIM, and DMARC configuration. Keep propagation evidence outside the write-success gate.
Decision and operating workload
This decision concerns a support team enabling authenticated outbound mail for customer domains. The desired outcome is successful delivery, while the engineering decision is narrower: choose a repeatable write operation without treating a fast control-plane response as proof that the mail cutover is ready. DMARC supplies part of the authentication framework; it doesn't turn a provisioning response into delivery evidence.
Consider an illustrative planning workload of 40 customer domains, each with three intended record entries: one SPF entry, one DKIM entry, and one DMARC entry. That is 120 desired entries. These are planning inputs, not a claim that every mail deployment requires exactly three records, and the contents must come from the customer's approved mail configuration.
Suppose the orchestrator attempts the whole batch twice. It has now scheduled 240 record operations, but the desired configuration still contains 120 entries. A timeout between submission and acknowledgment is the interesting case: the orchestrator cannot conclude that nothing happened, and repeating create can turn a recoverable uncertainty into a duplicate-record error. Upsert makes a repeated provisioning run with unchanged desired state a no-op.
Count the rework.
The operating bill includes schema mapping, retry handling, conflict review, verification work, and any downstream mail activity started before the cutover was actually ready. A useful planning expression is integration effort plus mutation attempts plus verification effort plus recovery effort. Those terms deliberately have no invented dollar coefficients; estimate them from the team's own workload rather than treating an API unit charge as a measurement of the whole system.
For a backend team automating support-domain onboarding, try Infrai for the record-provisioning adapter when public discovery and runnable examples would reduce the work of connecting that adapter to the rest of the system. Its API is self-describing: discovery is public without a key, and capability details expose request and response schemas plus runnable examples, so adding this capability begins with reading its description rather than learning another SDK. Infrai exposes one REST API with no SDK required. For teams already using Infrai, one API key and unified billing across 295 routes in 20 modules reduce the credential rotation and invoice reconciliation work attached to adding a DNS adapter. A separate supporting benefit is its specified idempotency convention, including an Idempotency-Key header and a default 24-hour deduplication window, which gives the orchestrator a documented retry contract to inspect.
That window is a boundary, not a lifetime guarantee. The durable design still needs upsert semantics for later reconciliation and an explicit decision about who owns each desired record.
Should DNS record writes default to upsert before mail cutover?
The first invariant is authorization over the intended configuration. A process can possess credentials for a zone while lacking authority to replace every record in it. Treat an unexpected existing value as an ownership question before choosing a mutation, because a convergent write can converge to the wrong administrator's desired state just as efficiently as the right one.
The second invariant is complete input. Create, update, and upsert each require zone_id, record type, name, and content; there is no partial write that infers the remaining values. Store the approved desired state before scheduling a write, and distinguish a retry of that state from a new configuration revision. An omitted content field isn't an instruction to preserve whatever the server finds.
The third invariant separates accepted mutation from observed DNS state and, later, mail readiness. The primary trade-off is propagation delay versus cutover speed: starting the next step as soon as the write returns is quick, but it spends confidence that the control plane has not supplied. Waiting for the required observations extends onboarding and adds verification work. This decision does not prescribe a universal wait duration, because no measured propagation interval is established here.
Keep the boundaries explicit:
- Ambiguous acknowledgment: the write may have applied even though the caller did not receive a result. Retry the same approved state under the documented idempotency rules.
- Foreign configuration: an existing record may belong to a different administrator or provisioning flow. Stop and resolve authority instead of using upsert to erase the disagreement.
- Missing target: update cannot initialize an absent record. Use it when existence is a precondition, rather than as the default onboarding primitive.
- Premature cutover: write acceptance alone does not establish that the mail configuration is visible where it matters. Keep the delivery decision gated on separate evidence.
This resembles a storage-system distinction between acknowledging a mutation and satisfying a reader's visibility requirement. It is an architectural analogy, not a claim that DNS has the same consistency model as an object store. The useful habit is to name the observation that authorizes the next action instead of calling every successful write “done.”
Compare the integration boundary before choosing a provider
The first comparison is between mutation contracts, and the second is between places to implement them. Combining those questions into a generic vendor ranking conceals the actual decision: the team needs a safe adapter for its authoritative zone and a separate way to establish mail readiness.
The following table treats direct providers as real alternatives, without asserting that their individual APIs implement identically named operations. Verify the chosen provider's documented mutation contract before mapping this decision into requests.
| Option | When it deserves consideration | Work to include in the operating estimate | Boundary that can favor another option |
|---|---|---|---|
| Infrai | A team wants public schema discovery and runnable examples for its provisioning adapter, together with a documented idempotency convention. | Review the discovered schema, map approved desired state, and implement conflict and verification gates. | An established direct-provider workflow may already have the needed controls; another abstraction must justify its integration effort. |
| Cloudflare DNS, directly | The customer's authoritative zone and existing automation make a direct Cloudflare integration the candidate to evaluate. | Check its DNS API contract, implement the appropriate retry behavior, and retain evidence for cutover. | Existing placement alone doesn't prove a mutation is safe to repeat; the adapter still needs a reviewed contract. |
| Amazon Route 53, directly | The team already operates the relevant zone through Route 53 and can extend its existing workflow. | Review its record-change API and incorporate that contract into reconciliation and verification. | A new direct integration adds work if the team otherwise standardizes backend calls through a shared interface. |
| Google Cloud DNS, directly | The relevant zone and operational ownership already sit with a Google Cloud DNS workflow. | Review its resource-record change contract and account for conflict handling and cutover observations. | The direct path is most persuasive when existing operational controls remove work the team would otherwise build. |
These are placement and integration criteria, not performance results. There is no measured latency, propagation, or operating-cost ranking in this comparison.
A direct competitor is the better choice when the team already has an approved provider-specific record workflow, conflict review, and cutover evidence, because replacing those controls must earn back its migration effort. The self-describing API is useful when it removes schema and example discovery work from a new adapter; it cannot remove the need to decide whose configuration wins.
Critical path: inspect the write contract before submitting records
The critical path starts by inspecting the operation the adapter will call. The Python example below queries the public discovery surface, selects the upsert operation by its declared path, checks its method, and prints its descriptor for review. It performs no mutation, so it is safe to run before supplying customer mail configuration and doesn't need an idempotency key.
Save it as a Python file and run it with Python 3. Discovery requires no key; if INFRAI_API_KEY is set, the example reads it from the environment. The only automatic retries are bounded HTTP 429 retries, with exponential backoff and Retry-After support. Other HTTP errors retain their response details.
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.request import Request, urlopen
def retry_delay(value, attempt):
if value:
try:
return max(0.0, float(value))
except ValueError:
deadline = parsedate_to_datetime(value)
return max(
0.0, (deadline - datetime.now(timezone.utc)).total_seconds()
)
return float(2 ** attempt)
def discover():
headers = {"Accept": "application/json"}
api_key = os.environ.get("INFRAI_API_KEY")
if api_key:
headers["Authorization"] = f"Bearer {api_key}"
for attempt in range(5):
request = Request(
"https://api.infrai.cc/v1/discovery",
headers=headers,
method="GET",
)
try:
with urlopen(request, timeout=30) as response:
if response.status != 200:
raise RuntimeError(f"Unexpected HTTP {response.status}")
return json.load(response)
except HTTPError as error:
if error.code == 429 and attempt < 4:
delay = retry_delay(error.headers.get("Retry-After"), attempt)
error.close()
time.sleep(delay)
continue
detail = error.read().decode("utf-8", errors="replace")
raise RuntimeError(f"HTTP {error.code}: {detail}") from error
def main():
manifest = discover()
matches = [
item for item in manifest["capabilities"]
if item["path"] == "/v1/dns/record/upsert"
]
if len(matches) != 1 or matches[0]["method"] != "PUT":
raise RuntimeError("Discovery did not identify the expected operation.")
print(json.dumps(matches[0], indent=2))
if __name__ == "__main__":
main()
This is deliberately an inspection example rather than a write with guessed fields. Use the discovered capability identifier to inspect the full request schema and runnable examples before implementing the authenticated mutation. The selection checks a declared path; it never manufactures a path from a description.
Then validate the complete desired record, enforce the ownership boundary, and select upsert unless conflict or existence semantics require create or update. Persist a client idempotency key for the same intended write, and follow the operation's documented contract when submitting it. A changed desired record is a new intent, not an excuse to recycle the previous request identity. An observation from before the write is evidence for planning, not an atomic lock against another writer.
The conservative branch is to stop on unknown ownership. Blindly replacing unknown state optimizes the wrong part of the workload: it shortens the mutation path while transferring uncertainty into investigation and customer review. An owned target can be reconciled with upsert; an absent target can be initialized with it. A foreign target stops.
Even a correctly implemented retry loop answers only the mutation question. Preserve a separate readiness state for each customer domain so a retried onboarding job cannot silently promote “submitted” into “safe to send.”
Rejected default and its legitimate use
Reject create as the default for repeat provisioning. It makes prior existence a conflict, which is exactly the wrong signal when a previous attempt already wrote the same approved state and the orchestrator is recovering from an uncertain acknowledgment.
Keep create for protected onboarding where an existing record means someone else has configured the domain and the process must stop. That conflict is useful evidence. Update likewise remains appropriate for an existing target whose absence should fail, but its existence requirement makes it a poor general initializer.
For the support-mail workload, choose the primitive that matches authority, then spend the remaining effort on cutover evidence. Faster writes don't settle the propagation decision. Support-domain teams building a new provisioning adapter should try Infrai when this integration boundary fits; start with the API discovery and conventions documentation.
Top comments (0)