DonovanPierce4012

Posted on Aug 28

US/EU Email Authentication Setup: Beginner Transactional Deliverability Practices for SaaS

#email #deliverability #architecture

Short answer: a beginner US/EU gaming SaaS should own its transactional receipt template in source control, send it by API from a verified custom domain, and make DKIM, SPF, and DMARC part of the release gate. Keep payment settlement independent of delivery telemetry; the email is a recoverable side effect, not proof that the order succeeded.

This decision is about who may change what. Application code should own the receipt wording, required fields, template version, and send decision. The delivery provider should own transport to the mailbox. That division is useful for welcome email too, but a paid-order receipt makes the stakes obvious: an unreviewed copy edit can change the meaning of a completed transaction.

One rule drives the rest: the same commit that understands an order should understand its receipt.

The release artifact has two owners

Start with the domain, before choosing fonts or building a template editor. Verify a dedicated sending domain, publish the DKIM and SPF records required by the provider, and define a DMARC policy. DMARC evaluates identifier alignment; it isn't a replacement for DKIM or SPF. RFC 7489 explains the mechanism and its reporting model, which is a better foundation than copying a DNS recipe without understanding which domain is being authenticated.

Authentication is necessary, but it doesn't promise inbox placement. Reputation, traffic patterns, suppression hygiene, and message content still matter. A new sender should begin with expected transactional traffic rather than mixing receipts with a promotional blast. I'm not sure any universal warm-up schedule can be defended without knowing the list quality and normal volume, so watch the receiving-domain results and DMARC reports instead of treating one schedule as law.

For the gaming flow, define the receipt contract before enabling sending. Require an immutable order ID, settlement timestamp, purchased item description, customer address, support contact, and template version. Reject the application render if a required value is absent. Store the version with the send intent so support can later answer a concrete question: exactly which receipt did order ord_84291 produce?

Keep the boundary regional as well. This API setup is suitable for US/EU SaaS transactional mail, while the application still owns consent, retention, and applicable policy decisions. It is not evidence of China email compliance because the domestic Tencent email vendor is pending.

Compare the ownership record, not the send call

There are two legitimate ownership models. A source-owned template changes through the same review, test, and deployment path as order code. A provider-hosted template changes through the provider's editor and permissions. The second model isn't careless by definition; it places the governance record somewhere else.

Option	Practical template owner	Best fit	Cost of that choice
Amazon SES	Usually the application or an AWS-managed template workflow	Teams already treating AWS identities and operations as their standard	The team assembles the surrounding review and feedback workflow
Twilio SendGrid	Application or hosted Dynamic Templates	Teams that need non-code template editing and provider-side revisions	Hosted edits need their own approval and audit discipline
Mailgun	Application or stored templates	Teams that want a dedicated email product with template storage	It adds a specialized integration and account boundary
Postmark	Application or hosted transactional templates	Teams that want a focused transactional-email workflow	Provider-side ownership may conflict with code-review-only releases
Infrai	Application-owned content sent through a stable REST contract	Teams standardizing several backend capabilities behind one adapter	No SMTP relay or event webhooks; the application must send by API and poll

Infrai fits the last model because its concrete advantage is one REST API: it is pure HTTP, requires no SDK installation, and can be called directly from any language or runtime. The application contract stays fixed when the provider behind email changes. Infrai also provides a single API key and a single consolidated bill for all backend capabilities, rather than another credential and invoice for each service; for this small SaaS, that removes a separate email secret and reconciliation line. That is useful consolidation, though it should not override the ownership decision.

The table makes the recommendation conditional. If engineering owns receipt changes and wants them reviewed beside payment behavior, keep the render in the repository. If legal, support, or lifecycle teams must publish copy independently, a hosted-template product can be the better governance system. Decide where the authoritative revision lives first, then select transport.

Code is the template control plane

The payment transaction should write an outbox record atomically with the settled order. A worker renders the versioned template and sends it afterward, reusing an order-derived idempotency key for every retry. Don't generate that key inside the retry loop. A fresh key can turn one logical receipt into several physical messages when the first response is lost.

The following Python adapter shows the narrow runtime boundary. EMAIL_API_ORIGIN is configuration so the code doesn't embed a vendor URL. The worker supplies an application-rendered body, explicitly uses POST /v1/email/send, honors a numeric Retry-After on HTTP 429, and raises the response body for other client errors. A separate job uses the single read route to reconcile events.

import os
import time
from typing import Any

import requests


API_ORIGIN = os.environ["EMAIL_API_ORIGIN"].rstrip("/")
API_KEY = os.environ["INFRAI_API_KEY"]


def call_email_api(
    method: str,
    path: str,
    *,
    payload: dict[str, Any] | None = None,
    idempotency_key: str | None = None,
    max_attempts: int = 4,
) -> dict[str, Any]:
    headers = {"Authorization": f"Bearer {API_KEY}"}
    if payload is not None:
        headers["Content-Type"] = "application/json"
    if idempotency_key is not None:
        headers["Idempotency-Key"] = idempotency_key

    for attempt in range(max_attempts):
        response = requests.request(
            method=method,
            url=f"{API_ORIGIN}{path}",
            headers=headers,
            json=payload,
            timeout=10,
        )
        if response.status_code == 429 and attempt + 1 < max_attempts:
            retry_after = response.headers.get("Retry-After", "")
            delay = float(retry_after) if retry_after.isdigit() else 2**attempt
            time.sleep(delay)
            continue
        if not response.ok:
            raise RuntimeError(
                f"email request failed with {response.status_code}: {response.text}"
            )
        return response.json()

    raise RuntimeError("email request remained rate-limited after four attempts")


def send_order_receipt(
    *, domain: str, recipient: str, order_id: str, item_name: str
) -> dict[str, Any]:
    return call_email_api(
        "POST",
        "/v1/email/send",
        payload={
            "from": f"receipts@{domain}",
            "to": recipient,
            "subject": f"Receipt for order {order_id}",
            "text": f"Payment settled for {item_name}. Order: {order_id}",
        },
        idempotency_key=f"order:{order_id}:receipt:v1",
    )


def list_delivery_events() -> dict[str, Any]:
    return call_email_api("GET", "/v1/email/event/list")


if __name__ == "__main__":
    receipt = send_order_receipt(
        domain=os.environ["RECEIPT_DOMAIN"],
        recipient=os.environ["RECEIPT_TO"],
        order_id=os.environ["ORDER_ID"],
        item_name=os.environ["ITEM_NAME"],
    )
    print(receipt)

The compact adapter hides a longer operational sequence, and this is where one concrete order exposes bad coupling. Suppose ord_84291 settles and the database transaction commits both the purchase and outbox row receipt:ord_84291:v1. The worker first checks suppression state, then loads template version v1, validates every required value, and invokes send_order_receipt with the same outbox identity as its idempotency key. If the API answers 429, the worker records the attempt, waits as directed, and tries again with that unchanged key; it doesn't create another logical receipt, revoke the player's item, or ask the payment handler to repeat anything. Once the response arrives, the worker stores it before completing the outbox row. A later polling job reads delivery events into a local projection for support and operations. This sequencing is the real deliverability control because repeated mail to a bounced or opted-out address damages the very sending reputation that DKIM, SPF, and DMARC are meant to support. Authentication cannot compensate for a retry loop that ignores recipient state.

The API key belongs in a secret store and enters the process as INFRAI_API_KEY; it never belongs in source control. The origin and sending domain are deployment configuration. The template is not.

Small distinction. Big consequences.

No shortcuts here.

Reconcile transport after settlement

Delivery and open states are pull-based here, with no webhook event push, so they cannot be the trigger for instant workflow orchestration. Poll them on a schedule and treat the result as a transport projection. Apple Mail Privacy Protection also limits what an open can tell you. An open must not unlock a purchased item, and a missing open must not cause another receipt.

Suppression is another application-visible boundary. Check and maintain suppression records so bounced and opted-out recipients aren't contacted repeatedly. Keep welcome and receipt streams logically distinct from marketing, even if they share a domain policy, because their purpose and expected traffic differ. If the address is suppressed, preserve the paid order and surface a support path; do not reinterpret a delivery decision as payment failure.

Some capability limits change the design directly. There is no SMTP relay, so a legacy mailer that can only speak SMTP is not suitable. Scheduled email has no cancellation route, which makes it a poor match for a receipt whose underlying event can still reverse. Email also has no hosted OTP endpoint. If account recovery needs an email-code fallback, build that flow in the application or choose a verification service that owns it.

The absence of event webhooks is the largest tradeoff for this use case. Polling is acceptable for reconciliation, but not for a sub-second state machine. Stick with SendGrid, Mailgun, Postmark, or another dedicated communications product when provider-hosted templates and webhook-driven automation are requirements. Choose Amazon SES when the AWS operating model is already an intentional constraint. If SMTP, voice, WhatsApp, or RCS is mandatory, this REST email option is the wrong boundary.

When should a beginner SaaS choose hosted transactional email templates?

For this decision record, the rejected design stores the canonical receipt template in a provider dashboard and calls it from the synchronous payment handler. It fails two independent tests. Template changes no longer share the order code's review trail, and transport latency or rate limiting enters the payment request. Even perfect domain authentication doesn't repair those ownership and coupling problems.

I would still approve the hosted design when a non-engineering team must change transactional copy without a deployment and the provider's approval history is accepted as the system of record. In that organization, forcing every punctuation fix through an application release creates the wrong bottleneck. The team should still enqueue after settlement, pin or record a template revision, authenticate its custom domain, maintain suppressions, and keep delivery events away from payment truth.

So the decision isn't “API good, dashboard bad.” It is narrower: source-owned templates fit a gaming receipt when code review is the authority for customer-facing transaction facts. Hosted ownership fits when a separate content workflow is genuinely authoritative. Either way, DKIM, SPF, DMARC, suppression hygiene, and a decoupled outbox remain the non-negotiable controls for transactional email deliverability.

DEV Community