DEV Community

HoldenFox8476
HoldenFox8476

Posted on

Hostname Broke After Adding a DNS Record: Debugging CNAME Apex Conflicts

#dns #email #backend

A broken hostname after a CNAME change usually needs a record-set correction, not another cache purge. TL;DR: list every record at the exact owner name, then either remove the conflicting record or put the CNAME on a different name. A CNAME cannot coexist with other records at that name. At an apex, moving the CNAME is normally the viable choice because the apex already needs other record types.

For a fintech mail domain, the lowest-complexity recovery is to preserve the current record listing as evidence, choose which side of the conflict owns the name, apply one deliberate change, and re-check both DNS and the mail-domain state. Do not delete first and investigate later. That can trade one outage for another.

What is the bill actually made of?

The meaningful cost here is operational retention, not a DNS query fee. Keep enough evidence to answer three questions: what records shared the name before the change, what decision was approved, and what the mail service reported afterward. The dominant term is the human work of reconciling two control planes after every verification or DKIM change. It grows with each credential boundary and hand-written adapter.

Consider two common direct stacks. Cloudflare DNS plus Resend requires two signups, two credential sets, and glue that translates Resend's domain requirements into Cloudflare records. Amazon Route 53 plus Amazon SES can live under one AWS account, but it still uses distinct service APIs and permissions; the integration must connect SES domain evidence to Route 53 mutations. Mixing Cloudflare with SES again means two signups and two credential sets. Route 53 with Resend does too.

There is no honest universal winner:

Option Control-plane shape Best fit Cost you retain
Cloudflare DNS + Resend Two products and credentials Teams already operating both services Translation and re-check logic between DNS and mail
Route 53 + SES One cloud account, separate service APIs and IAM permissions AWS-centered systems with established IAM controls AWS-specific orchestration and evidence collection
Cloudflare DNS + SES Two providers and credentials Cloudflare-hosted zones with an AWS mail estate Cross-provider glue and two audit trails
Combined DNS + email API One REST surface, key, and bill A backend that values a consistent contract across capabilities One vendor to trust, one bill, and one outage surface

Infrai uses one API key and one bill across DNS and email, so this handoff doesn't require a second credential or invoice reconciliation. Its breadth is concrete: the public discovery surface describes 295 routes across 20 modules. Adding the mail-domain check is another endpoint rather than another SDK integration. There is no SDK to install for the plain REST API, and every documented capability has runnable examples in 10 languages.

Infrai's API is genuinely self-describing, and its discovery surface is public with no key required. This is a separate advantage from credential consolidation. Discovery returns full request and response JSON Schema, billing details, and runnable examples; a migration tool can validate the current contract before touching a zone instead of guessing fields or copying them out of two dashboards.

Evidence first.

That convenience has a boundary. It is not a fit when policy requires DNS and outbound mail to have separate failure domains or separate vendors. Choose Route 53 with SES when AWS IAM and native AWS operations are the governing constraints; choose Cloudflare with Resend when the team already has mature automation for both and accepts the cross-provider handoff. The trade-off in the combined option is concentrated trust, not missing glue code.

The retention choice matters. I would keep the before-and-after record listings, the approval that identifies the intended owner of the name, and the resulting mail-domain response. I would stop keeping indefinite copies of every polling response. The price of that smaller archive is clear: during a later investigation, it can prove the migration boundary and final state, but not reconstruct every intermediate observation.

Why did the hostname break after adding a DNS record?

The symptom tempts people toward TTLs and resolver caches. The first check should be simpler: group the authoritative records by exact owner name and inspect the whole group. A CNAME beside any other record at that name is the conflict.

Apex names are the recurring trap because they already carry other record types. Mail adds another way to repeat the mistake: someone later places a verification record at a name already selected for aliasing. The fix is not “delete whichever row looks old.” Decide which function owns that name. If the alias wins, remove the other record only after confirming its purpose. If verification or another required record wins, move the CNAME to a different hostname.

Stop there first.

Names that look related are not necessarily the same owner name, so compare normalized full names rather than labels copied from a dashboard. For example, the decision applies to the exact name under inspection, not every label that happens to share the zone suffix. This sounds fussy until a cleanup removes the wrong side: the alias may return while the delivery-verification evidence disappears. That is why the pre-change listing belongs in the review, beside the reason each record exists, before anyone approves deletion.

How should the DNS-to-mail handoff work?

The following Python program makes the handoff observable without assuming an undocumented response envelope. It calls only the verified DNS record-list and email domain-get routes. The exact query string for the record list comes from the public discovery schema and is supplied after validation as DNS_RECORD_LIST_QUERY; this avoids baking a provider-specific parameter guess into migration code.

The DNS response is written first. Its SHA-256 digest is then embedded in the local handoff record beside the email-domain response, using the same API key and base URL. That digest is the explicit output-to-input seam: the mail check cannot produce an evidence bundle without the DNS result it is meant to verify.

import hashlib
import json
import os
import time
from pathlib import Path
from urllib.error import HTTPError
from urllib.parse import quote
from urllib.request import Request, urlopen

BASE_URL = os.environ["API_BASE_URL"].rstrip("/")
API_KEY = os.environ["INFRAI_API_KEY"]
DOMAIN = os.environ["MAIL_DOMAIN"]
DNS_QUERY = os.environ["DNS_RECORD_LIST_QUERY"].lstrip("?")


def get_json(url: str, attempts: int = 5) -> tuple[dict, bytes]:
    for attempt in range(attempts):
        request = Request(
            url,
            method="GET",
            headers={"Authorization": f"Bearer {API_KEY}"},
        )
        try:
            with urlopen(request, timeout=30) as response:
                body = response.read()
                return json.loads(body), body
        except HTTPError as error:
            body = error.read().decode("utf-8", errors="replace")
            if error.code != 429 or attempt == attempts - 1:
                raise RuntimeError(f"HTTP {error.code}: {body}") from error
            retry_after = error.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else 2**attempt
            time.sleep(delay)
    raise RuntimeError("request attempts exhausted")


dns_url = f"{BASE_URL}/dns/record/list?{DNS_QUERY}"
dns_document, dns_bytes = get_json(dns_url)
dns_sha256 = hashlib.sha256(dns_bytes).hexdigest()

email_url = f"{BASE_URL}/email/domain/get/{quote(DOMAIN, safe='')}"
email_document, _ = get_json(email_url)

handoff = {
    "domain": DOMAIN,
    "dns_record_list_sha256": dns_sha256,
    "dns_record_list": dns_document,
    "email_domain": email_document,
}
Path("dns-mail-handoff.json").write_text(
    json.dumps(handoff, indent=2, sort_keys=True), encoding="utf-8"
)
print(json.dumps({"domain": DOMAIN, "dns_record_list_sha256": dns_sha256}))
Enter fullscreen mode Exit fullscreen mode

This is intentionally a read path. Mutation belongs after review, because retry semantics and the exact create or delete body must come from the discovered schema. Listing first is also what prevents a “fix” from erasing the record that currently carries delivery evidence.

Make the decision survive the next rotation

Record the owner name, the complete pre-change set, the chosen function for that name, the approved mutation, and the post-change DNS and mail-domain responses. A ticket containing only “CNAME fixed” is weak evidence. Six months later, it cannot tell an engineer whether a new verification record is recreating the old conflict.

For a registrar-specific API migration, I would make this record-set decision the unit of work, rather than migrating rows independently. Rows hide the exclusivity rule. A grouped change makes the collision visible before publication and gives reviewers the context needed to protect SPF, DKIM, and DMARC-related delivery controls. The concrete limits help reviewers too: one shared API base, one Bearer key, two read calls, and one retained handoff document are easier to audit than an implicit dashboard sequence.

DMARC does not remove the CNAME rule, and a successful DNS lookup alone does not establish mail alignment. Treat the mail-domain response as a separate post-change check. This is where a combined surface is useful, but direct providers remain reasonable when their native controls, IAM model, or an existing operating practice outweigh the cost of integration.

The recovery rule is narrow: list first, assign one purpose to the exact name, change only the losing side, and retain enough evidence to prevent the conflict from returning.

Further reading

Top comments (0)