Transactional emails

Discover how to use transactional emails for real-time customer communication.

Learn about API integration, tracking, custom templates, bounce management, and email fallback to enhance your user experience with Bloomreach Engagement.

The transactional email API is disabled by default. To configure this API in your project, contact your Customer Success Manager. We will set up the email API for you based on your needs.

Learn more about how to use the Transactional email API method in our API Reference.

Send transactional emails

You can trigger sending a transactional email through:

• API that triggers a template
• API that sends raw HTML
• A scenario

Unlike sending transactional emails through a scenario, the transactional API has its own infrastructure. Thus, other running campaigns do not influence their throughput, ensuring the speedy delivery of transactional emails. For example, if a user sends an extensive marketing campaign that drains resources, it does not affect the transactional API; while it would affect transactional emails triggered via scenarios.

Track transactional emails

Transactional email API is tracked in the same way as classical emails, but it tracks fewer event properties. For example, no campaign_policy is tracked. It is also different from the classical email campaign in the following ways.

Transactional email API:

• Allows attachments
• Has a separate queue from other on-event scenarios
• Cannot be used for bulk emailing
• Does not include an unsubscribe header

Transactional emails are tracked with transactional_email in the action_type property of the campaign.

In terms of the campaign_id, campaign_name, and other properties of the campaign event, you can manually specify what should be used as, for example, a campaign_id via an API call.

In general, the transactional API also does not take into account our bounce management, as per the info below.

Bounce management and transactional email API

In general, the transactional email API does not consider our bounce management. We always try to send the email, with a single exception, which is basic email address validation. In more detail:

• Transactional API ignores email_invalid
• Delivery webhooks from the transactional API do generate standard bounce events, the same as standard emailing

For cumulative bounce specifically:

• Cumulative bounces from the transactional API are counted into the rules as consequent soft bounces
• A temporary ban is not applied
• A permanent ban is not applied (transactional API ignores email_invalid)

Template settings

You can also define email template settings as part of the payload. Settings defined here have a higher priority over the ones defined within the template in the Bloomreach Engagement app. These settings involve custom event properties (see custom tracking), custom headers, URL parameters, and transfer identity. See the API reference for more details.

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

Custom tracking

You can use custom tracking attributes in transactional emails. This can be done either by defining these attributes in the used email template, or directly within the payload as a JSON object which contains attributes that should be tracked in the email events. Read more about custom tracking in transactional emails.

Transactional email fallback

Transactional email fallback is an optional module for you. You can specify 2 ESPs integrations for emails sent through transactional email API to ensure high availability and mitigate the impact of any outages on the side of ESP. The module can be disabled/enabled per account and you will need two email providers integrated into your project to use it.

Module implementation

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

How to use email fallback

To use the email fallback you need to use a new parameter field integrations in the Transactional API. The parameter is an array of objects (1 or 2 items) containing the Email Service Provider integration IDs along with corresponding sender addresses. Each object must contain 2 required parameters:

The module does not affect the current integration_id field already in transactional API. If both integrations and integration_id fields are provided, only the integrations field is used. It works similarly when you provide both integrations -> sender_address and email_content -> sender_address fields, only the integrations -> sender_address will be used.

How email fallback works

The high availability is ensured by using 2 ESP integrations that are in normal circumstances used evenly for sending transactional emails. In case sending via one of the integrations is not successful the system will fall back to the other integration.

The transactional email fallback module behaves differently when it is turned on and turned off. The behavior itself indicates its state when using a different number of integration IDs. To read more about the exact behavior, refer to the Transactional API reference guide.

Module on

When the module is turned on:

• When the integrations field contains only 1 ID, there is no change in the behavior except using its accompanied sender_address. The provided integration will be used and the attempt will succeed or fail.
• When there are 2 integration IDs in the integrations fields, the system will randomly choose one of the integrations to use for sending the email. This means that the two integrations are used evenly for emails. In case sending via the selected integration is not successful the system will fall back to the other integration. This is to ensure both ESPs remain “warmed up”.

Module off

When the module is turned off, the behavior when the integration field contains only one ID is the same as when the module is turned on. In other words, there is no change in behavior except using its accompanied sender_address. However, when the integration field contains 2 IDs, only the first ID will be used, and the attempt will succeed or fail.

Frequency policy

The Frequency policy does not apply to transactional emails.