Integrate transactional email

Define transactional email requirements

Record each email as a separate requirement. Include its recipient, trigger, template, locale source and fallback, acceptable delivery delay, and tolerance for a missing or duplicate email. Also decide how long delivery records must remain available for support and audit purposes.

• Decide whether Customer creation sends an email for every Customer or only for Customers created through specific Stores.
• Define the token lifetime, delivery policy, and verification URL for email verification and password reset. Treat a missing token email as a blocking failure and protect the token as a secret.
• Decide which Order creation flows send a confirmation. Include imported and recurring Order creation when those flows are in scope.
• Allowlist the Order and shipment states that warrant a customer email.
• Describe return-information changes as return updates. Use an authoritative payment event when the email must state that money was refunded.

Record special requirements separately because they can change the application design:

• Define how multi-Store or multi-brand integrations select sender identities and templates.
• Define B2B recipients and any Business Unit-specific templates.
• Verify attachment support and size limits with the provider.
• Use a separate authenticated service application when provider bounce or complaint webhooks must update commercetools.
• Use a separate job application for batch or digest emails.

For each requirement, classify a duplicate and a missing email by business impact. This decision controls when the Connector acknowledges a Message and whether it needs durable deduplication.

Choose a Connector path

Understand the Connect application model

Do not use an API Extension to send transactional email. An API Extension runs synchronously in a commercetools API request, so provider latency or an outage could delay or reject a Customer or Order operation.

Use an existing integration

For each candidate, verify the following before installation:

• It is deployable through Connect and supports your Region.
• Its contract includes the required Message types, templates, locale behavior, and provider.
• Its acknowledgment, retry, deduplication, and permanent-failure policies match your requirements.
• Its source, lifecycle behavior, security controls, tests, and operational runbook meet your production standards.

If configuration covers the requirements, use the existing Connector. This avoids maintaining a fork for a difference that a template mapping, state allowlist, or locale setting can resolve.

Create your own integration

If no existing Connector fits, choose one of these paths:

1. Fork a source-available Connector when it already implements most of the required contract and has a specific code gap.
2. Customize the transactional email integration template when you need its Subscription and routing scaffold.
3. Build a new event application when the scaffold or an existing Connector would require broader changes than your own focused implementation.

Configure the Connector and email provider

Configure the event application

Configure the email provider

Prefer templates that the provider hosts and that the Connector references by ID over rendering email markup in the Connector. Provider-hosted templates let non-technical teams change copy and layout without redeploying the Connector, and they keep the application a thin data-mapper. Render inside the Connector only when the provider offers no template feature or you require full control over the output.

Create the provider templates and define their required variables before implementing the mapping. Verify the sender address or domain with the provider. A provider can reject an unverified sender or accept the request without delivering the message to the inbox.

Manage the Subscription lifecycle

Map Customer and Order Messages

The Subscription filter and handler router must contain the same explicit set of Message types. Broad resource subscriptions increase cost and can route unrelated Messages into email logic.

Map each email requirement to its Subscription filter value:

Re-fetching also has a consequence for state emails. Because asynchronous Messages are not ordered, the retrieved Order can already have a later state than the transition recorded by the Message. Choose and test one policy:

• Use the transition represented by the Message to decide whether to send, then use the retrieved Order only for current template data.
• Use the current retrieved state and intentionally collapse intermediate transitions.

Implement the event handler

Process each delivery in this order:

1. Decode the envelope for the configured destination and validate the notification type.
2. Validate and route the Message type. Positively acknowledge irrelevant, valid Messages instead of retrying them.
3. Establish the delivery record or deduplication key required by the selected delivery policy.
4. Retrieve the Customer or Order when full or current data is required.
5. Select the locale and template, then map the resource to the provider variables.
6. Call the provider or durably enqueue the send.
7. Persist the provider acceptance or terminal failure state before returning the final acknowledgment.

Keep the Message-to-provider mapping as a pure function. Test recipient and template selection, locale handling, money formatting, date formatting, optional fields, and state allowlists without calling commercetools or the provider.

The provider boundary must use the provider SDK or transactional API. Classify provider rate limits, timeouts, and server errors as transient. Classify invalid recipients, invalid templates, and rejected sender configuration as permanent according to the provider contract. Retry transient failures. For permanent failures, record the failure, alert the operator, and positively acknowledge or quarantine the event so it does not retry forever.

Choose delivery and deduplication behavior

The following diagrams compare the end-to-end flow for each policy. They show when the Connect application acknowledges the event, how failures affect delivery, and whether the Subscription can redeliver the Message.

As a default, use at-most-once for Order and account confirmations, where a rare missed email is tolerable and a duplicate is merely unwelcome. Use at-least-once with deduplication for drop-intolerant emails, such as email verification and password reset, where a missing email blocks the Customer. Record the chosen policy for each email type.

The audited template has no durable deduplication or provider-acceptance record, and it does not implement provider idempotency. Add these controls before changing the template to acknowledge after a send.

Design for an ambiguous provider result instead of assuming that every email is delivered exactly once. The provider can accept a request while the Connector times out before receiving the response. On retry, use the same provider idempotency key where supported, and reconcile an ambiguous result against provider activity before sending again.

Handle tokens, state transitions, localization, and personal data

Protect token flows

Preserve state meaning

Test the chosen transition policy with rapid consecutive Order updates. The email subject, body, and send condition must all refer to the same transition or intentionally selected current state. A retrieved current state must not silently change the meaning of an earlier Message.

Localize with a fallback

Keep logs safe

Log a correlation key, Message type, resource ID, attempt, duration, provider result category, and deduplication state. Do not log full Message bodies, recipient addresses, names, token values, or template data. The audited scaffold logs several of these values and must be changed before production use.

Verify and operate the integration

Before deployment, add focused automated tests for the following behavior:

• The route matches the connect.yaml endpoint, and each supported destination envelope is decoded correctly.
• Every selected Message type routes to the intended template; unselected types are acknowledged without a send.
• Resource retrieval handles omitted payloads, missing resources, and a resource that has advanced to a later state.
• State allowlists, locale selection, and fallback behavior are deterministic.
• The selected acknowledgment policy handles provider success, transient failure, permanent failure, timeout, and duplicate delivery.
• Deduplication survives process restart and concurrent handling.
• Token handling prevents self-trigger loops and repeated creation.
• postDeploy creates or updates one Subscription, repeated deployment does not duplicate it, and preUndeploy removes it.
• Logs and errors do not expose Customer data or tokens.

After deployment, verify the complete provider flow:

1. Confirm that one Subscription exists with the expected key, destination, and Message filters.
2. Trigger every supported Message through a representative Customer or Order operation.
3. Confirm the Connector receives the event and finishes within the acknowledgment deadline.
4. In the provider activity log, confirm the recipient, template, locale, and non-sensitive template data.
5. Confirm inbox delivery using an approved live test recipient. Provider acceptance alone is not proof of delivery. A provider sandbox can accept a request while suppressing inbox delivery or restricting recipients.
6. Redeliver the same event or replay an equivalent fixture. Confirm the result matches the selected duplicate policy.
7. Force a transient provider failure and confirm retry or durable-queue recovery. Force a permanent failure and confirm alerting without an endless retry.
8. Exercise rapid state transitions, a return update, a token flow, and locale fallback.

Monitor Subscription health, event age, processing duration, acknowledgment failures, provider response categories, retries, and deduplication conflicts. Also monitor permanent failures and provider delivery outcomes. Define how operators replay failed work without bypassing deduplication. Account for queue delivery delay and cold starts when setting an alert threshold. Subscription delivery has no guaranteed time frame and can be delayed by several minutes.

Troubleshoot observable symptoms