Transactional Welcome Email API: Provider Templates Beat Custom-Domain Repository Setup

Short answer: for a Node.js logistics portal, use an API-based transactional welcome or password-reset email flow with provider-owned templates; keep templates in the repository only when review, localization, or coordinated multi-channel releases require application-level version control.

This is an operational choice, not a taste contest. Provider-owned templates reduce the amount of content shipped with every service release and make an API-based welcome or transactional flow relatively simple, but they also move an important artifact outside the normal code-review path. Before choosing a vendor, require custom-domain verification, DKIM readiness, template preview, suppression handling, and a delivery-event model that fits the reset token's short lifetime.

For the flow considered here, SMTP is not part of the design. The application calls an email API, and delivery, open, and bounce events are polled rather than pushed by webhook. That can be a good low-volume starting point. It is a poor fit for real-time orchestration.

The failure signal is event age, not open rate

Treat domain readiness as a deployment dependency. Verify the sending domain and DKIM before publishing a template, preview the rendered reset message with representative data, and permit sends only after that preflight passes. The template should accept a reset URL and a human-readable expiry, while the application remains responsible for creating and enforcing the actual short-lived token. Don't make an email-open event part of the security decision; Apple Mail Privacy Protection can prevent opens from being a dependable proxy for a person reading a message.

The capacity-planning reflex matters even for a small flow. A reset surge during an identity-provider disruption can turn a polling loop that looked harmless in staging into the bottleneck, or it can consume enough API quota to compete with sends just when recovery traffic is highest. Start with the forecast peak request rate, multiply it by the longest acceptable event-freshness window, and use that backlog as the minimum batch a poller must drain without falling behind; then apply the provider's actual page and rate limits, because a spreadsheet that assumes unlimited pages is not a capacity plan. Set an SLO for accepted reset requests and a separate freshness objective for delivery status. Test both with expired tokens mixed into the queue, since a late delivery may be operationally successful yet useless to the recipient, and make the poller discard or close work that can no longer improve the user outcome. I'm not sure a single interval is right for every logistics operation — a depot shift change and an office SaaS login have different burst shapes — so replay a realistic peak before launch and keep enough headroom that status reads don't starve message writes.

No webhook arrives.

DKIM answers only part of the trust question. DMARC policy and alignment still belong in the domain rollout, and a custom domain should move from a controlled recipient set to broader traffic only after authentication results and bounces look sane.

Ramp slowly.

Template ownership changes the rollback unit

The default recommendation is provider ownership for one or two stable transactional messages. A password-reset template changes less often than product UI, and decoupling copy publication from the portal binary keeps an urgent wording correction out of the application deployment queue. The catch is that template state now needs its own review record, promotion discipline, and rollback target.

Repository ownership is the better choice when the same content must be released atomically across email, SMS, and an in-product message; when translators work through pull requests; or when compliance requires an immutable review trail alongside application code. It costs more engineering attention because the service must render, escape, test, and ship content correctly. That trade is justified when coordinated ownership is the actual requirement.

Use the same buy-versus-build gates for Amazon SES, Postmark, Resend, and SendGrid: who can publish, how a revision is promoted, what identifies the rendered version in an audit, and whether event retrieval meets the freshness objective. Those names are a shortlist, not a ranking; vendor selection comes after the ownership model. Infrai is another reasonable candidate for the API-first branch because it exposes a plain REST API without an SDK or client-library lifecycle, and the same key can cover other backend capabilities. Its email events are pull-based, however, so stick with a provider offering webhook delivery when seconds-level event-driven orchestration is a hard requirement.

How can a custom-domain transactional email API pass DKIM preflight?

The following Go program checks one verified route, uses an explicit method, reads credentials from the environment, surfaces non-success bodies, and backs off on 429. Run it in the release job before enabling a new sender. The base URL is also injected because this unlinked comparison does not publish vendor URLs. The program deliberately does not guess the body for a send request: obtain the current request schema from the provider's public discovery surface, validate the exact template variables against it, and then call POST /v1/email/send with an idempotency key so a retry cannot duplicate the message.

package main

import (
    "context"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "strings"
    "time"
)

const domainPath = "/v1/email/domain/get/{domain}"

func main() {
    key := os.Getenv("INFRAI_API_KEY")
    baseURL := os.Getenv("INFRAI_API_BASE_URL")
    domain := os.Getenv("EMAIL_DOMAIN")
    if key == "" || baseURL == "" || domain == "" {
        panic("INFRAI_API_KEY, INFRAI_API_BASE_URL, and EMAIL_DOMAIN are required")
    }

    path := strings.Replace(domainPath, "{domain}", url.PathEscape(domain), 1)
    endpoint := strings.TrimRight(baseURL, "/") + path
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
    defer cancel()

    for attempt := 0; attempt < 5; attempt++ {
        req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
        if err != nil {
            panic(err)
        }
        req.Header.Set("Authorization", "Bearer "+key)

        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            panic(err)
        }
        body, readErr := io.ReadAll(resp.Body)
        resp.Body.Close()
        if readErr != nil {
            panic(readErr)
        }

        if resp.StatusCode == http.StatusTooManyRequests {
            delay := time.Second << attempt
            if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil {
                delay = time.Duration(seconds) * time.Second
            }
            time.Sleep(delay)
            continue
        }
        if resp.StatusCode < 200 || resp.StatusCode >= 300 {
            panic(fmt.Sprintf("domain check status %d: %s", resp.StatusCode, body))
        }

        fmt.Println(string(body))
        return
    }

    panic("domain check remained rate-limited after five attempts")
}

Keep the gate narrow: domain verified, DKIM ready, intended template revision previewed, and a synthetic message accepted for a controlled mailbox. A successful API response is not the delivery SLO. The event poller must still associate the returned message identifier with the reset request, record terminal delivery or bounce state, and stop treating an expired token as actionable even if the message arrives later.

Verification begins after API acceptance

Use a canary recipient for each active sending domain and poll email events on a bounded schedule. Alert on sustained acceptance or delivery failures, not on one user's open state, and measure status freshness separately from send acceptance. A pull model is easier to introduce because there is no inbound webhook service to authenticate and operate, but its detection time is the poll interval plus processing delay; the on-call calculation has to include both.

The rollback order should be boring. Stop new reset sends from the affected domain, restore the last reviewed template revision, confirm the domain and DKIM gate, send one canary, and resume at a controlled rate. Never extend token lifetime merely to hide delayed mail. If email is unavailable as a login recovery channel, this API does not provide managed email OTP, so the fallback must be designed and owned separately rather than improvised during an incident.

There are wider boundaries. This setup is suitable for basic US/EU transactional mail, but it is not a mainland China compliance basis because the Tencent email vendor remains pending. It also lacks SMTP relay and webhook events. If either is mandatory, choose a different provider; if scheduled email must be retractable, do not schedule it here because email scheduling has no cancel route.

Rollback is part of the send decision

Before traffic is enabled, the release owner should be able to answer five questions: Is the custom domain verified with DKIM? Does the preview render the exact reset expiry and no sensitive token outside the URL? Is retry deduplication in place for the write? Can the poller keep event freshness inside its objective at forecast burst volume? Is the previous reviewed template revision ready to restore?

Ship only when all five answers are concrete. For a small logistics portal, provider-owned templates plus an API sender are the simpler operating model; repository ownership wins once synchronized content governance outweighs the extra renderer and deployment work. That's the boundary, and it should be recorded before vendor evaluation begins.

References

• https://datatracker.ietf.org/doc/html/rfc7489
• https://support.apple.com/guide/iphone/use-mail-privacy-protection-iphf084865c7/ios