Use a declarative MX configuration with explicit priorities, upsert its entries, and require readback plus mail-delivery evidence before retiring the previous provider. For a healthtech hostname cutover, the deciding constraint is whether the team can prove routing works and restore the previous configuration without guessing what it contained.
Short answer: configuration defines the intended MX records; upsert makes those entries re-applicable; listing verifies the result. Removal is separate. An upsert of the new configuration does not delete the old provider's records.
This architecture decision record targets a Node.js backend that owns the cutover workflow. The focused Python example below checks configuration and readback independently of the application runtime. It operates on local data: the critical decision is whether the observed set matches the approved set, and no request payload schema needs to be guessed to demonstrate that check.
How should configuration set MX records with explicit priorities before a cutover?
Treat the hostname change as a mail-routing decision with an explicit acceptance record. A successful DNS write establishes that a mutation was accepted. It doesn't establish that a message reached its intended mailbox. In a healthtech workflow, that distinction should shape the release decision: record the approved configuration, the observed MX set, the synthetic delivery result, and the rollback decision together. Use test messages without patient information. Evidence should explain the routing decision without becoming another store of clinical content.
Keep evidence narrow.
The illustrative configuration uses priorities 10 and 20 for a primary and a fallback destination. These are example values, not measured recommendations. An equal-priority pair cannot express that primary/fallback distinction. Explicit priority belongs in configuration review alongside the destination hostname; a reviewer shouldn't have to infer the intended order from array position.
Acceptance has two independent parts. First, list the records after applying the change and compare their destinations and priorities with configuration, including unexpected records. Second, require a successful synthetic delivery check under the team's chosen release criteria. Neither check substitutes for the other. DMARC is relevant to the authentication review, but an authentication policy isn't evidence that the intended mailbox received the test message.
For an OTP or notification workflow, write down what the probe actually establishes. In this proposed release process, a receipt artifact identifies the synthetic message, the destination mailbox, and whether the team's delivery deadline was met. Choose that deadline from the application's requirements rather than inventing a universal DNS acceptance threshold. A message accepted for processing and a message available to its recipient are different checkpoints. The cutover decision needs the latter evidence for the tested path.
Invariants and failure boundaries
The controller owns an explicitly identified MX set for one hostname. Preserve the prior approved set before changing it, retain explicit priorities, and refuse to interpret a missing or additional record as success. Keep unrelated DNS records outside the mutation scope. Those are proposed controller invariants, rather than guarantees supplied by every DNS interface.
The awkward boundary is deletion. Applying the desired entries with upsert converges those entries, but it doesn't make the entire observed set equal to configuration if obsolete entries remain. Full reconciliation therefore needs both insertion or update and explicit removal. Readback must check extras as well as missing records; checking only that the new primary exists leaves an old destination invisible to the acceptance gate.
That's the trap.
Rollback has the same boundary. Reapplying the previous configuration restores its entries, but records introduced during the attempted cutover still require explicit cleanup. Keep the previous provider available until the acceptance decision is complete, and review the cleanup scope before executing it. A rollback path that has no record of the prior fallback destination is incomplete even if the primary destination is known.
DNS control and message receipt also have different evidence boundaries. The record list tells the controller what it can observe through that interface. The delivery probe tells the operator what happened to a particular test message. Avoid turning either result into a broader claim about all messages or all recipients. This matters for an OTP or notification workflow because a single successful probe is a release signal with a defined scope, not a universal delivery guarantee.
Compare options by the evidence they let you retain
The useful comparison is which operational boundary the team wants to own. The table gives selection criteria for three real DNS products and one broader backend option; it doesn't rank unmeasured delivery performance. DNS product choice alone cannot establish mailbox receipt.
| Option | Reason to evaluate it for this cutover | Limitation or trade-off to inspect |
|---|---|---|
| Amazon Route 53 | A candidate when AWS is already the team's DNS operating context. | Review how the proposed integration represents the full MX set and records rollback evidence; keep the mail-delivery acceptance gate explicit. |
| Cloudflare DNS | A candidate when the hostname is already operated through Cloudflare. | Review the integration's update and deletion scope, especially whether old MX entries remain after the desired entries are applied. |
| Google Cloud DNS | A candidate when Google Cloud is already the team's DNS operating context. | Review how configuration approval, readback, and rollback artifacts fit the existing release process. |
| Consolidated backend API | One key and one bill reduce credential and invoice coordination; a plain REST API with no SDK required lets the Python readback job run independently of the Node.js deployment. | A broader backend interface isn't necessary for a DNS-only change. Prefer the existing DNS product when retaining its established approval and rollback process matters more than consolidating integrations. Public, self-describing discovery exposes request schemas without a key for adapter review; it doesn't supply mailbox-delivery evidence. |
Infrai offers one key and one bill for backend services, plus a plain HTTP API with no SDK required. This single API lets a Python release check read DNS independently of the Node.js application's SDK dependencies. Its self-describing discovery surface is public with no key required, so an adapter reviewer can inspect request schemas before obtaining a production credential. Documented capabilities include runnable examples in 10 languages. These are integration benefits; neither credential consolidation nor schema visibility replaces the receipt gate.
These are fit criteria, not assertions that one product delivers mail better. Route 53, Cloudflare DNS, and Google Cloud DNS are distinct operating contexts; the existing account, approval process, and DNS ownership should decide which deserves the first adapter review. The comparison deliberately makes no unsupported claim about their relative delivery rates or migration speed. Require each candidate to demonstrate the same upsert, explicit deletion, and readback workflow before selection.
A team with an established DNS operating process may reasonably prefer to keep the cutover there. A team consolidating backend integrations may value the broader interface. In either case, ask for the same evidence artifact before advancing the release.
Check the critical path before allowing cleanup
Start with readback.
This Python 3 example makes the record-list request through the consolidated API. Set INFRAI_API_ORIGIN to its reviewed HTTPS API origin, without a path, and INFRAI_API_KEY to the credential. Supply DNS_LIST_QUERY_JSON as a JSON object containing the query parameters from the public record-list request schema for your hostname. This keeps vendor fields out of the example rather than guessing their names. The program prints the actual response; an operator must inspect and map it before running the comparison below.
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 urlencode, urlsplit
from urllib.request import HTTPRedirectHandler, Request, build_opener
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
origin = os.environ["INFRAI_API_ORIGIN"].rstrip("/")
parts = urlsplit(origin)
if (
parts.scheme != "https"
or not parts.netloc
or parts.path
or parts.query
or parts.fragment
or parts.username
or parts.password
):
raise ValueError("INFRAI_API_ORIGIN must be a reviewed HTTPS origin")
params = json.loads(os.environ["DNS_LIST_QUERY_JSON"])
if not isinstance(params, dict):
raise ValueError("DNS_LIST_QUERY_JSON must contain a JSON object")
query = urlencode(params, doseq=True)
url = origin + "/v1/dns/record/list" + ("?" + query if query else "")
request = Request(
url,
method="GET",
headers={"Authorization": "Bearer " + os.environ["INFRAI_API_KEY"]},
)
opener = build_opener(NoRedirect())
for attempt in range(4):
try:
with opener.open(request, timeout=30) as response:
if response.status != 200:
raise RuntimeError(f"Unexpected HTTP status: {response.status}")
print(response.read().decode("utf-8"))
break
except HTTPError as error:
detail = error.read().decode("utf-8", errors="replace")
if error.code != 429 or attempt == 3:
raise RuntimeError(f"HTTP {error.code}: {detail}") from error
delay = float(2 ** attempt)
retry_after = error.headers.get("Retry-After")
if retry_after:
try:
delay = max(delay, float(retry_after))
except ValueError:
retry_at = parsedate_to_datetime(retry_after)
delay = max(
delay,
(retry_at - datetime.now(timezone.utc)).total_seconds(),
)
time.sleep(delay)
The request is read-only, so retrying it cannot duplicate a DNS write. The example uses a 30-second request timeout and at most 4 attempts; those are local guardrails, not service guarantees. It honors a returned retry delay and otherwise backs off exponentially. Redirects are rejected so the credential stays at the reviewed origin. Use a restricted release environment and inspect returned errors before retaining them in an audit artifact.
This runnable Python 3 preflight checks the Node.js controller's decision rule. The dictionaries are an internal configuration format, not a DNS vendor's request or response schema. The hostnames use reserved example names. Adapt actual record-list responses into this internal representation only after checking the selected interface's schema. This example exercises the acceptance boundary without making a network request or changing DNS.
from collections import Counter
def record_key(record):
priority = record["priority"]
if type(priority) is not int or not 0 <= priority <= 65535:
raise ValueError("MX priority must be an integer from 0 to 65535")
exchange = record["exchange"]
if not isinstance(exchange, str) or not exchange.strip():
raise ValueError("MX exchange must be a nonempty hostname")
return priority, exchange.strip().rstrip(".").lower()
def compare(desired, observed):
wanted = Counter(record_key(record) for record in desired)
actual = Counter(record_key(record) for record in observed)
return {
"missing": list((wanted - actual).elements()),
"unexpected": list((actual - wanted).elements()),
}
previous = [
{"priority": 10, "exchange": "mx.old.example"},
{"priority": 20, "exchange": "fallback.old.example"},
]
desired = [
{"priority": 10, "exchange": "mx.new.example"},
{"priority": 20, "exchange": "fallback.new.example"},
]
# Simulate readback after upsert left an old provider record behind.
observed = desired + [previous[0]]
difference = compare(desired, observed)
print("Cutover readback:", difference)
assert difference["unexpected"] == [(10, "mx.old.example")]
assert compare(desired, desired) == {"missing": [], "unexpected": []}
# Reapplying the previous entries alone leaves new entries to remove.
rollback_observed = previous + desired
rollback_difference = compare(previous, rollback_observed)
print("Rollback readback:", rollback_difference)
assert len(rollback_difference["unexpected"]) == 2
print("Local checks passed; delivery evidence is still required.")
The first comparison intentionally exposes a stale record. The rollback comparison then exposes two new records that restoring the old entries would leave behind. These assertions test the failure boundary that matters here: presence of the desired records is weaker than equality of the managed set. Case and trailing-dot normalization prevent a representational difference from obscuring that check. The example validates a narrow internal format; it isn't a complete DNS hostname validator. The 0–65535 check validates the MX preference field, while the choice of 10 and 20 expresses this example's intended order.
In the deployed workflow, apply the configured entries, list records, and classify the difference. An unexpected entry becomes a reviewed deletion candidate only within the controller's ownership scope. After approved cleanup, read back again and evaluate the delivery evidence. If the intended set is present but the receipt evidence is absent, leave the release unapproved and use the saved configuration to guide rollback. Reconcile that rollback too. Restoring entries without removing the attempted replacement leaves the same ambiguity in reverse.
Keep the production adapter separate from this local check. Its request fields must come from the selected service's documented contract; the local exchange key is no promise about any vendor's wire format. The adapter must use explicit HTTP methods, surface failed responses, back off on rate limits, and make write retries idempotent. Those are implementation requirements for the controller, not features demonstrated by this local program.
Rejected option: approve the cutover when upsert succeeds
A write-only release gate is rejected for this healthtech cutover. It cannot distinguish a clean replacement from a configuration containing both providers, and it supplies no evidence that the tested message reached the intended mailbox. The failure can stay quiet until mail bounces. Approval should therefore retain both set comparison and delivery evidence.
There is a valid narrower use case: preparing desired entries before the actual release decision. An operator may run upsert as a staging step while keeping cleanup and delivery acceptance pending. That step should be labeled preparation, with the prior configuration retained and the release gate still closed. It becomes a mistake only when its successful return value is promoted into evidence of completed mail delivery.
References
- RFC 7489, Domain-based Message Authentication, Reporting, and Conformance: https://datatracker.ietf.org/doc/html/rfc7489
- RFC 5321, Simple Mail Transfer Protocol, including MX destination selection: https://datatracker.ietf.org/doc/html/rfc5321
- RFC 1035, domain name resource record definitions: https://datatracker.ietf.org/doc/html/rfc1035
- Amazon Route 53 developer guide: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/Welcome.html
- Cloudflare DNS documentation: https://developers.cloudflare.com/dns/
- Google Cloud DNS documentation: https://cloud.google.com/dns/docs
Top comments (0)