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 parameter | Object type | Description |
id | string | The ID of the Email Service Provider integration. |
sender_address | string | The 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.