Transactional emails

A transactional email is a method of customer communication in which automated, real-time messages are sent to users through email after a specific action has been performed within an application or website.

We make it possible to trigger Transactional emails via our API and send them through Bloomreach Engagement. Please note that the transactional email API is disabled by default. To configure this API in your project, please contact your Customer Success Manager. We will set up the email API for you based on your needs.

📘

You can learn more about how to use the Transactional email API method in our API Reference.

Tracking

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 take into account 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

Optionally, you can 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 with which you can specify two 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.

Steps needed to implement the module

  • 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 it

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:

Required parameterObject typeDescription
idstringThe ID of the Email Service Provider integration.
sender_addressstringThe email address that will be used as the email's sender, overrides any other ways of supplying this parameter.

🚧

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 it works

The high availability is ensured by using two 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.

When the module is turned on:

  • When the integrations field contains only one 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 two 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”.

When the module is turned off:

  • In case 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 two ids, only the first id will be used and the attempt will succeed or fail.

🚧

Please bear in mind that Frequency Policy does not apply to transactional emails.