Transactional emails

Transactional emails let you communicate with customers in real time using API integration, custom templates, and email fallback. The transactional email API is disabled by default. To enable it for your project, contact your Customer Success Manager.

Learn more about the Transactional email API method in the API reference.

Send transactional emails

You can trigger a transactional email through 3 methods:

• An API call that triggers a template.
• An API call that sends raw HTML.
• A scenario.

Unlike transactional emails sent through a scenario, the transactional email API has its own infrastructure. This means other running campaigns don't affect its throughput, ensuring fast delivery. For example, if an extensive marketing campaign drains resources, it doesn't affect the transactional email API. It would, however, affect transactional emails triggered via scenarios.

Track transactional emails

The transactional email API is tracked in the same way as standard emails, but it tracks fewer event properties. For example, no campaign_policy is tracked.

The transactional email API also differs from standard email campaigns in the following ways:

• Allows attachments.
• Has a separate queue from other on-event scenarios.
• Can't be used for bulk emailing.
• Doesn't include an unsubscribe header.

The system tracks transactional emails using transactional_email in the action_type property. Unlike other campaign types with predefined campaign IDs, transactional emails work differently. When you send them through the API, you manually set the campaign_name, and the system automatically uses this same value for the campaign_id.

Bounce management

In general, the transactional email API doesn't follow standard bounce management rules. The system always attempts to send the email, with 2 exceptions: basic email address syntax validation and a check against the global suppression list of common invalid and spam trap domains.

The transactional email API ignores email_invalid. Delivery webhooks from the transactional API generate standard bounce events, just as email does.

For cumulative bounces:

• Cumulative bounces from the transactional email API are counted as consecutive soft bounces toward the rules.
• A temporary ban is not applied.
• A permanent ban is not applied, as the transactional email API ignores email_invalid.

Template settings

You can define email template settings in the payload. Settings defined in the payload take priority over those defined in the template in the Bloomreach UI. These settings include:

• Custom event properties (see custom tracking below).
• Custom headers.
• URL parameters.
• Transfer identity.

To retrieve params from the payload for the email template, use the Jinja reference {{event.ParamProperty}}.

See the API reference for details.

Custom tracking

You can use custom tracking attributes in transactional emails. Define these attributes in the email template or directly in the payload as a JSON object containing the attributes to track in email events. Read more about custom tracking in transactional emails.

Transactional email fallback

Transactional email fallback is an optional module that lets you specify 2 ESP integrations for emails sent through the transactional email API. This ensures high availability and reduces the impact of ESP outages. The module can be enabled or disabled per account. You need 2 email providers integrated into your project to use it.

Implement the module

1. Add a second ESP integration, create a new subdomain, and set up all necessary records.
2. Agree on a warm-up plan with the email deliverability team and prepare for execution.
3. Update your API calls to the transactional email API and include the new integration and sender domain used with the new vendor.

Use email fallback

To use email fallback, include the new integrations parameter field in the Transactional email API. This parameter is an array of objects containing 1 or 2 items, each with an ESP integration ID and the corresponding sender address. Each object must contain 2 required parameters:

The module doesn't affect the current integration_id field in the transactional email API. If both integrations and integration_id fields are provided, only the integrations field is used. Similarly, if both integrations > sender_address and email_content > sender_address are provided, only integrations > sender_address is used.

How email fallback works

High availability is ensured by using 2 ESP integrations, each used evenly to send transactional emails under normal conditions. If sending via one integration fails, the system falls back to the other.

The module behaves differently depending on whether it's turned on or off, and on the number of integration IDs provided. For exact behavior details, see the Transactional email API reference.

Module on

When the module is turned on:

• 1 integration ID: No change in behavior except using the accompanied sender_address. The provided integration is used, and the attempt succeeds or fails.
• 2 integration IDs: The system randomly selects one integration to send the email, using both integrations evenly. If sending via the selected integration fails, the system falls back to the other. This ensures both ESPs remain warmed up.

Module off

When the module is turned off:

• 1 integration ID: Behavior is the same as when the module is on. No change except using the accompanied sender_address.
• 2 integration IDs: Only the first ID is used. The attempt succeeds or fails with no fallback.

Frequency policy

The Frequency policy doesn't apply to transactional emails.