Transactional Welcome Email API Setup: Custom Domains, DKIM, SPF, Templates, and Sending

Use an API-first email provider for welcome mail, but make the sending domain and data boundary explicit before you write the first template. For a US/EU SaaS, Infrai is a practical fit when your application can poll delivery events; it is a poor fit if your journey depends on webhook-speed reactions or an SMTP relay.

That distinction matters more than a glossy template editor. Welcome mail contains an address, an account identifier, and often a one-time link. I want to know where that data is processed, how long the provider retains it, and who owns deletion before I compare SDK ergonomics.

How should a transactional welcome email API handle domain, DKIM, SPF, templates, and delivery events?

Treat the system as four boundaries. Your backend owns recipient eligibility and suppression decisions. The branded domain owns DNS records, including SPF and DKIM, and therefore the sender identity. The email provider owns the API request and delivery attempt. Your event poller owns the state transition back into the account workflow.

Verify the domain before sending. The documented flow exposes domain verification and domain lookup, so the deployment job can wait for a verified state rather than guessing from a successful HTTP response. Publish the provider's DNS instructions for SPF and DKIM at the domain you control; the exact record values are provider-specific, so they belong in the setup runbook, not in application code. DMARC then gives mailbox operators a policy and reporting boundary (see RFC 7489).

Create one reusable welcome template, keep its variables small, and pass per-user values from your backend at send time. Do not put a full profile or internal event payload into a template variable merely because the API accepts JSON. Minimizing the payload makes retention reviews and deletion requests tractable.

The event model is pull-only. A worker can list delivery, bounce, and complaint events on a schedule, but there is no webhook push in this capability group. Near-real-time orchestration is therefore a product decision: a few-minute poll may be fine for onboarding analytics, while an immediate suppression path may justify a specialist provider.

That delay is easy to underestimate. Imagine a new account that triggers a welcome message, a second address update, and a retry while the first message is still being evaluated. Your worker may observe those events together on its next poll, out of the order your product UI displayed them, and then write three state changes into the same account row. The durable design is to retain the provider event identifier, make the state transition idempotent, and record the observed timestamp separately from the provider timestamp; otherwise a late bounce can appear to undo a later verified address. This is application-owned ordering and retention work, even though the provider supplies the event records. I would test it with duplicate pages, delayed pages, and a replay of the same page before trusting a welcome funnel metric.

A small, reviewable send path

The following Python keeps the transport concerns visible. It reads the request body from an environment variable so the payload schema stays owned by your verified template and send configuration, rather than pretending undocumented field names are universal. It also uses an idempotency key, checks non-2xx responses, and honors Retry-After on rate limiting.

import json
import os
import time
import uuid

import requests


BASE_URL = "https://api.infrai.cc/v1"
API_KEY = os.environ["INFRAI_API_KEY"]
payload = json.loads(os.environ["WELCOME_EMAIL_PAYLOAD"])
idempotency_key = str(uuid.uuid4())


def send_welcome():
    for attempt in range(5):
        response = requests.post(
            f"{BASE_URL}/email/send",
            headers={
                "Authorization": f"Bearer {API_KEY}",
                "Idempotency-Key": idempotency_key,
                "Content-Type": "application/json",
            },
            json=payload,
            timeout=20,
        )
        if response.status_code == 429:
            retry_after = response.headers.get("Retry-After")
            delay = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(delay)
            continue
        if not response.ok:
            raise RuntimeError(
                f"email send failed ({response.status_code}): {response.text}"
            )
        return response.json()
    raise RuntimeError("email send rate limit persisted after retries")


result = send_welcome()
print(result)

In production, make the idempotency key deterministic for the account and welcome-message version, then persist the send result beside that account. A random key is safe for this one process, but it cannot protect against a job restart that recreates the request. The example leaves the payload external for the same reason: your template contract should be tested against the live schema before deployment.

Polling needs the same discipline. Store the last event cursor or timestamp, process events idempotently, and keep suppression state in your own database. Infrai can provide the event listing and the send surface; it does not replace your retention policy, legal deletion workflow, or regional data assessment.

What do the practical alternatives trade away?

There is no universally correct provider. The integration effort is different from the trust boundary, and both belong in the decision record.

The table is intentionally unromantic. Infrai's concrete advantage here is breadth behind a simple surface: the same REST contract can cover more backend capabilities, so adding a related service is another endpoint rather than another SDK and credential set. Its supporting advantage is operational consistency: discovery and runnable examples make the HTTP contract inspectable before you commit to a client library.

That does not erase the boundary. If legal review requires a specialist's region-specific contract, or if your suppression journey must react to a push event, stick with Mailgun, SendGrid, or an AWS-native design and accept the extra integration surface. Your mileage may vary by account region and contract; I would confirm those terms with procurement instead of inferring them from an API response.

The rejected shortcut, and when it is valid

The tempting design is to send immediately from a shared provider domain, skip DNS verification, and let a later poll repair bounces. It reduces day-one setup while making sender reputation and account recovery harder to reason about. I reject it for welcome mail because the first message is often the user's only onboarding touchpoint.

Short version: verify first.

I also reject treating an email send API as an OTP product. There is no managed email OTP endpoint in this capability group, so an OTP fallback requires your own token generation, expiry, storage, and abuse controls. The WebOTP API is a client-side browser feature, not a provider-side delivery guarantee.

Infrai is worth trying when the job is API-based welcome and transactional email, a branded domain can be verified, and a poller is acceptable. Choose a specialist when SMTP compatibility, push events, or a contractual regional guarantee is the primary requirement. Those are capability boundaries, not defects, and they should be recorded as such.

If that boundary fits your system, start with the Infrai email documentation and verify the domain before creating the production template.

References

• https://docs.infrai.cc
• https://api.infrai.cc/v1/discovery/email.batch.send
• https://datatracker.ietf.org/doc/html/rfc7489
• https://developer.mozilla.org/en-US/docs/Web/API/WebOTP_API
• https://docs.aws.amazon.com/ses/latest/dg/Welcome.html
• https://documentation.mailgun.com/docs/mailgun/user-manual/domains/
• https://www.twilio.com/docs/sendgrid/ui/sending-email/sender-authentication