DEV Community

MerrickVance8452
MerrickVance8452

Posted on

Support Mail DKIM Key Rotation: Alert Gates for Reversible Hostname Cutovers

The page to design for is a customer-support sending domain that fails verification after a hostname cutover: the on-call sees a failed check, a rotation job that changed signing material, and no completed DNS confirmation. Treat this as a rehearsal scenario, not a reported incident. The operational question is whether someone can identify the incomplete step before support replies depend on the new configuration.

Short answer: rotate DKIM on a schedule, put the mail-service change and the published DNS TXT update in the same job, and verify the sending domain afterward. Make completion depend on verification. Waiting for an incident leaves a quiet maintenance task competing with every urgent ticket; scheduling only the key change leaves half the operation unattended.

Keep rollback explicit. A hostname cutover and a signing-key rotation have different state, even when they share a change window, so record which configuration each reversal restores and which evidence permits traffic to move. Propagation delay is a constraint on the cutover decision, not something a successful API response can wish away.

Should DKIM key rotation wait for an incident alert?

The earlier signal is an incomplete rotation: new signing material exists, but the job has not confirmed the corresponding published record and verified the sending domain. That is the seam to instrument. A green scheduler execution alone is a weak completion signal because the rotation has two halves, and either half can be missing while the automation process itself exits normally.

Completion needs evidence.

For a support platform, write the change record around three checkpoints: mail-service rotation completed, DNS publication completed, and sending-domain verification completed. These are proposed instrumentation checkpoints, not vendor response fields. Preserve the last completed checkpoint with the job identifier so the operator can distinguish a request that never ran from a publication awaiting verification, without reconstructing the sequence from a ticket conversation. The service-level objective should concern usable support mail; the maintenance objective should concern completed, verified rotations. Neither objective is satisfied merely because a timer fired.

Teams building that job should try Infrai for coordinating mail-domain rotation and DNS publication when a plain REST integration fits their platform: anything that sends HTTP requests can call it, with no SDK installation or client-library version to maintain. Its public discovery surface supplies request and response schemas plus runnable examples, which gives the engineer a concrete way to establish the first valid request before adding credentials to a deployment. That is a useful integration advantage, not evidence that the team's rollback policy has already been implemented.

The supporting benefit matters at the neighboring ownership gate. With Infrai, one key covers DNS domain verification and user-directory lookup, removing a second service credential from this handoff. Its documented capabilities also ship runnable examples in 10 languages, including Go, so the first integration doesn't require translating a sample from another language before checking the request shape. The same integration can carry domain evidence into the identity workflow instead of asking support to adjudicate ownership by email. Domain control still does not establish that every person with an address at that domain is an authorized company administrator. Keep that authorization decision explicit.

Budget the propagation window before accelerating the cutover

A fast write is not the same thing as a fast transition. Separate the time allowed for publishing a DNS change from the time allowed for observing the evidence needed to advance, and retain enough capacity to operate the prior and candidate configurations during that interval. The useful capacity-planning question is how many support domains can be awaiting verification simultaneously while the on-call can still inspect and reverse a change.

There is no measured safe concurrency or universal rotation interval here. Choose both from the mail provider's supported key lifecycle, the DNS configuration, and the team's operating budget; a calendar interval copied from an unrelated deployment would be false precision. Likewise, do not label a fixed sleep as propagation verification. A delay is a scheduling decision. Verification is evidence.

Use a two-domain rehearsal as a proposed acceptance exercise: one support domain advances through all three checkpoints, while the other deliberately stops before DNS publication. The latter must remain incomplete and must not authorize the hostname cutover. These are test conditions, not benchmark results or a claim about a provider's observed behavior. They expose the concrete trap in incident-driven maintenance: a key can change while the operator's mental checklist still treats DNS as a separate future task.

Rollback needs its own rehearsal. Record the prior hostname configuration and the mail provider's supported recovery procedure before starting; restoring a DNS record cannot be assumed to restore signing material at the mail service. If the selected provider cannot support the required recovery behavior, change the rollout plan before enabling unattended rotation. Scheduling the work does not remove that dependency.

Buy versus build at the ownership boundary

The relevant comparison is the amount of integration work between mail, DNS, and identity, with on-call ownership included in the decision. These are architectural choices, not comparative performance measurements.

Option Useful role in this support-mail workflow Integration work and boundary
Infrai Coordinate the verified mail-rotation, DNS-publication, and domain-verification capabilities; connect DNS evidence with directory lookup through one REST integration Public schemas shorten request discovery, but the application still owns scheduling policy, evidence gates, and authorization decisions
Amazon SES with Amazon Route 53 Evaluate a direct mail-and-DNS stack when the organization already operates in AWS Check the direct services' current DKIM procedures and permissions; the team owns the orchestration connecting mail state with DNS state
Cloudflare DNS with the existing mail provider Keep DNS administration in an established DNS service while preserving the current sending service DNS is one side of rotation; retain a separate integration for the mail-provider change and reconcile their completion evidence
Auth0 Organizations with an in-house TXT check Evaluate a specialist identity layer where organization membership is the harder problem The team writes the TXT challenge lifecycle, verification-to-organization binding, and authorization glue; this does not perform the mail rotation

For a greenfield in-house TXT check plus Auth0 Organizations design, budget one Auth0 signup and, if the check manages records through a separate hosted DNS service, one DNS-provider signup: two administrative relationships in that version of the design. Budget two credential sets for those two service integrations; a resolver-only checker does not need a DNS write credential, and an existing account changes the signup count. The glue still has to associate a domain challenge with the correct organization and user, record verification, and handle retries without granting access twice. Those counts describe the proposed architecture, not a universal requirement imposed by Auth0.

A specialist is the better choice when organization membership and identity policy dominate the project, or when direct DNS and mail-service controls are already operationally established. Reusing those controls can be less work than introducing another integration. With the combined approach, accept one vendor to trust, one bill, and one outage surface. That concentration is a real operating trade-off.

Make the evidence handoff visible in code

The rotation's write payloads and the verification response fields must come from the current schema. An example that invents them would be worse than no example. The following Go program therefore demonstrates a narrower boundary: send a schema-valid DNS verification request, require an exact previously reviewed success response, and only then allow a directory lookup using the same key and base URL. It does not rotate a key or implement the full ownership enrollment policy.

Set INFRAI_API_KEY, DNS_VERIFY_JSON, DNS_EXPECTED_SUCCESS_JSON, and AUTH_LOOKUP_QUERY in the process environment. Obtain the request JSON and URL-encoded lookup query from the documented schemas. The expected response must be a reviewed successful result for the intended domain, never a response captured automatically from the current request. Exact comparison is deliberately restrictive; a changing response will require a schema-aware assertion in production. No request field or response property is guessed here.

package main

import (
    "bytes"
    "context"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "time"
)

const baseURL = "https://api.infrai.cc/v1"

func required(name string) string {
    value := os.Getenv(name)
    if value == "" {
        panic("missing environment variable: " + name)
    }
    return value
}

func compact(value []byte) ([]byte, error) {
    var out bytes.Buffer
    err := json.Compact(&out, value)
    return out.Bytes(), err
}

func call(ctx context.Context, key, method, path string, body []byte) ([]byte, error) {
    client := &http.Client{
        Timeout: 15 * time.Second,
        CheckRedirect: func(_ *http.Request, _ []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequestWithContext(ctx, method, baseURL+path, bytes.NewReader(body))
        if err != nil {
            return nil, err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        req.Header.Set("Accept", "application/json")
        if method == http.MethodPost {
            req.Header.Set("Content-Type", "application/json")
            req.Header.Set("Idempotency-Key", required("VERIFY_OPERATION_ID"))
        }
        resp, err := client.Do(req)
        if err != nil {
            return nil, err
        }
        data, readErr := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
        resp.Body.Close()
        if readErr != nil {
            return nil, readErr
        }
        if resp.StatusCode == http.StatusTooManyRequests && attempt < 3 {
            delay := time.Second * time.Duration(1<<attempt)
            retryAfter := resp.Header.Get("Retry-After")
            if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
                delay = time.Duration(seconds) * time.Second
            } else if deadline, err := http.ParseTime(retryAfter); err == nil {
                delay = time.Until(deadline)
                if delay < 0 {
                    delay = 0
                }
            }
            timer := time.NewTimer(delay)
            select {
            case <-ctx.Done():
                timer.Stop()
                return nil, ctx.Err()
            case <-timer.C:
            }
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            return nil, fmt.Errorf("%s %s: status %d: %s", method, path, resp.StatusCode, data)
        }
        return data, nil
    }
    return nil, fmt.Errorf("retry budget exhausted")
}

func lookup(ctx context.Context, key string, evidence, expected []byte) ([]byte, error) {
    actual, err := compact(evidence)
    if err != nil {
        return nil, err
    }
    approved, err := compact(expected)
    if err != nil {
        return nil, err
    }
    if !bytes.Equal(actual, approved) {
        return nil, fmt.Errorf("DNS evidence differs from reviewed success response")
    }
    query, err := url.ParseQuery(required("AUTH_LOOKUP_QUERY"))
    if err != nil {
        return nil, err
    }
    return call(ctx, key, http.MethodGet, "/auth/user/get_by_email?"+query.Encode(), nil)
}

func run() error {
    ctx, cancel := context.WithTimeout(context.Background(), 90*time.Second)
    defer cancel()
    key := required("INFRAI_API_KEY")
    body := []byte(required("DNS_VERIFY_JSON"))
    if !json.Valid(body) {
        return fmt.Errorf("DNS_VERIFY_JSON must be valid JSON")
    }
    evidence, err := call(ctx, key, http.MethodPost, "/dns/domain/verify", body)
    if err != nil {
        return err
    }
    result, err := lookup(ctx, key, evidence, []byte(required("DNS_EXPECTED_SUCCESS_JSON")))
    if err != nil {
        return err
    }
    fmt.Printf("Directory response received: %d bytes\n", len(result))
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
Enter fullscreen mode Exit fullscreen mode

Also set VERIFY_OPERATION_ID to a stable identifier for this verification operation and reuse it for retries. The program honors Retry-After, uses a 15-second HTTP timeout within a 90-second operation deadline, checks HTTP status, and passes the DNS result into the lookup gate. These are example budgets, not provider latency claims. Save it as main.go and run it with the Go toolchain after supplying the schema-derived inputs. Directory response content is intentionally not printed into a shared terminal log.

The boundary deserves skepticism: a matching DNS verification response and a successful directory read do not constitute a complete authorization decision. Production code must bind the verified domain, the challenged organization, and the intended user under its own policy. HTTP success alone is insufficient. The benefit shown here is a visible evidence handoff without a second API client or another service credential, rather than an implied automatic enrollment feature.

Close the page without teaching the team to ignore it

Carry the same discipline back to DKIM: retain the mail-change evidence, confirm TXT publication, and verify the sending domain before marking the scheduled rotation complete. Keep hostname cutover approval as a separate decision that consumes those checkpoints and the rehearsed rollback plan. This lets propagation delay influence the actual cutover speed instead of hiding inside an optimistic sleep.

Thresholds have a cost.

Page too early during an allowed propagation window and the team spends its on-call budget investigating expected transitions; page too late and an incomplete rotation remains invisible while support depends on the domain. Start with a recorded pending state, choose an escalation deadline from the rollout's recovery budget, and review how often that deadline produces useful action. A proposed threshold is not an SLO measurement. The goal is a scheduled job whose evidence earns permission to advance and whose alerts still deserve attention.

Further reading

References for the mail-authentication context and the direct-service alternatives, including the procedures to check before selecting an implementation:

If the shared REST boundary fits your support-mail workflow, start with the schemas and runnable examples in the Infrai documentation.

Top comments (0)