Transactional email

/email/v2/projects/{projectToken}/sync

This method allows you to trigger Transactional Emails from our API and send them through Bloomreach Engagement.

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.

Learn more in our Transactional emails article.

🚧

Incorrect code displays

Note that some language versions incorrectly display "params": { \"first_name\": \"Marian\" } instead of "params": { "first_name":"Marian" }.

Definition

Authorization

In this API call you must use the following authorization access and permissions:

Available access typePermissions needed
Private accessCampaigns > Transactional email API

Read more about:

Path parameters

ParameterTypeDescriptionRequired
projectTokenstringThe ID of your project.Required

Body Parameters

ParameterTypeDescriptionRequired
integration_idstringThe ID of your Email Service Provider integration. This can be found in the URL of the selected integration.Optional: If you have set a default email provider in the project settings this field is not required - the default provider will be used.
integrationsObject (1 or 2 items)Define one or two Email Service Provider integrations IDs along with corresponding sender addresses to enable Transactional Email Fallback feature..
If there are more than 2 items in the object, the request will be rejected with the HTTP code 400 Bad Request.
In case this parameter is defined, the integration_id parameter is ignored.
Optional parameter if integration_id is used, Required for Transactional email fallback
email_contentobjectDefine the content of the email. This can be either by using an existing Bloomreach Engagement template, or through raw HTML. Learn more below.Required
campaign_namestringThe name of the email campaign.Required
recipientobjectDefine the recipient of this email.Required
transfer_identitystringWhether link transfer ability should be enabled. Possible values:

1. enabled - default value, appends iitt parameter, which identifies on all clicks;
2. disabled - appends nothing to the links, no identity transfer;
3. first_click - appends xnpe_tifc, which identifies on first click only;
Optional
settingsobjectJSON object containing currently supported email template settings. Settings defined as part of the payload will override any settings pre-configured within a used template.Optional

🚧

transfer_identity default behavior

The default behavior is enabled, which is all clicks identification. However, it's important to note that this does not necessarily match the default configuration in the project/email template, which might normally be first click identification.

Email_content object parameters

There are two ways in which you can define the content of your email through this API method.

  1. Using Bloomreach Engagement template: Create an email template in Bloomreach Engagement and then send it through API.
  2. Through raw HTML: Define the email in raw HTML and CSS using the html and subject parameters.

The definition of the email_content object will differ based on which way you want to specify the content. Please, find the description of the object parameters for both of the outlined ways below.

(1) Using Bloomreach Engagement template

ParameterTypeDescriptionRequired
template_idstringThe ID of the email template that you wish to send out. This can be found in the URL when you go to the selected predefined template.Required
sender_addressstringThe email address of the sender.No
sender_namestringThis is usually a first name of sender.No
paramsobjectProvide all the required data for email personalization used in the template. Format: "param_name":"value".

For example:
"first_name":"Marian"
No
attachmentsjsonSpecify the attachment of your email.

filename: The name of the attachment
content: Encoded content of your file (base64)
content_type: The format of your attachments
No

🚧

Template_id from the Asset Manager

You can only take template_id from templates from the Asset Manager. This cannot be used for templates stored under Email Campaigns.

(2) Through raw HTML

ParameterTypeDescriptionRequired
htmlstringDefine the content of the email between <html></html> tags. CSS is also accepted.

Jinja is not evaluated in this field.
Required
subjectstringDefine the email subject.

Jinja is not evaluated in this field.
Required
sender_addressstringThe email address of the sender.Required
sender_namestringThis is usually a first name of sender.Required
attachmentsjsonSpecify the attachment of your email.

filename: The name of the attachment
content: Encoded content of your file (base64)
content_type: The format of your attachments
No

🚧

Either the template_id or a combination of html and subject are required. You cannot use both at the same time.

Recipient object parameters

ParameterTypeDescriptionRequired
emailstringSpecify the email of the customer. If the email is not provided, it will be taken out from the customer profile in Bloomreach Engagement based on the customer ID.Optional
customer_idsstringSpecify the customer that should receive your email.

You can use any type of customer ID. Common examples would include registered or email.
Required
languagestringLanguage version of your template. If the template has several language versions created, you can choose which one to use for this email.Optional

Settings object parameters

Please note that in all parameters, Jinja is not allowed and the request will fail if it’s present.

ParameterTypeDescriptionRequired
custom_event_propertiesobjectJSON object containing custom attributes in the following (name:value) format:
{
”: “
}
Name and value can be a string or number.
Optional
custom_headersobjectJSON object containing request headers that will be sent to the email provider. Format:
{
”: “
}
Name and value can be a string or number.
Optional
url_paramsobjectJSON object which contains URL parameters used for tracking in session start events for example (More info).
{
”: “
}
Name and value can be a string or number.
Optional
transfer_user_identitystringWhether link transfer ability should be enabled. Possible values:

1. enabled - default value;
2. disabled;
3. iitt - do not transfer identity into the linkThis setting is the same as the transferidentity parameter directly in the body of the request (see above). *_Note that only one can be specified. Specifying transfer identity as part of the settings as well as alone will result in an error.

*This is the recommended way of defining this setting
Optional
consent_categorystringSpecify the consent category of the customer if you wish to respect the consent in the Engagement platform (more info).Optional
consent_category_trackingstringSpecify the tracking consent category of the customer if you wish to respect the tracking consent in the Engagement platform (more info).Optional

Integrations object parameters

ParameterTypeDescriptionRequired
idstringThe ID of the Email Service Provider integration.Required
sender_addressstringEmail address that will be used as the email's sender for this integration, overriding any other ways of supplying this parameter.Required

Header

ParameterTypeDescriptionRequired
authorizationstringUsed for authentication. Read more in the Authentication section.Required
content-typestringapplication/jsonRequired

Additional payload example

{
   "integration_id":"5b337eceeb7cdb000d4e20f3",
   "email_content":{
      "html":"<!DOCTYPEhtml><body>Hello world</body></html>",
      "subject":"SubjectExample",
      "sender_address":"[email protected]",
      "sender_name":"Marian"
   		"attachments":[
         {
            "filename":"example.txt",
            "content":"RXhhbXBsZSBhdHRhY2htZW50",
            "content_type":"text/plain"
         }
      ]
   },
   "campaign_name":"MyCampaign",
   "recipient":{
      "customer_ids":{
         "registered":"3232eroofs23fsdsd"
      },
      "email":"[email protected]",
      "language":"nl"
   },
    "settings": {
       "custom_event_properties": {
           "banana": "yellow",
       }
   },
   "transfer_identity":"enabled"
}

📘

It is possible to send over a set of params in the payload that are then accessible in the template via Jinja utilizing the structure params.attribute_name or event.attribute_name.

❗️

Please do not use the JSON element name items: [] as this can conflict with the Jinja personalisation language, and cause error responses in your API call. Use a name like products: [] or similar instead.

Example of errors which may occur: "Failed to render the template: content HTML: filter 'list': 'builtin_function_or_method' object is not iterable"

Transactional emails are tracked with thetransactional_email in the action_type property of the campaign.
In terms of the campaign_id, campaign_name, and other properties of the campaign event, through an API call, you can manually specify what should be used as, for example, a campaign_id.

Transactional Email Fallback Behaviour

Transactional Email Fallback module is turned ON

1.: When integrations field contains only one id, there is no change in the behaviour except using its accompanied sender_address. The provided integration will be used and the attempt will succeed or fail.

2.: When integrations field contains two integration ids, the system will randomly choose one of the integrations and will try to use it for sending the email. This means that the two integrations will be used evenly for sending the emails. In case sending via the selected integration is not successful the system will fallback to the other integration. This is to ensure both ESPs remain “warmed up”.

3.: When the first attempt is successful a campaign event with status=enqueued will be created and the integration_id property will contain the first (successful) integration id.

4.: When the attempt to send email with the first randomly chosen integration id fails, the second integration id will be used.

5.: When the second attempt is successful a campaign event with status=enqueued will be created and the integration_id property will contain the second (successful) integration id and attempts property will contain the number of attempts = 2. The API response will contain a warning in the warnings field of the JSON response about the fallback.

Example:

{
   "success":true,
   "message":"Email was sent successfully.",
   "warnings":[
      "Fallback required, integration 5b337eceeb7cdb000d4e20f3 (mailgun): Email sender rate limit reached"
   ]
}

6.: When the attempts to send email with both integrations fail, the API request will fail with - usually HTTP code 502 Bad request. A campaign event with status=enqueue_failed will be created and the integration_id property will contain both failed integration ids (array of strings) and attempts property will contain the number of attempts = 2.

In case one of the integration id does not point to an existing email integration it will be ignored and we will automatically fallback to the other integration. The API response will contain a warning in the warnings field of the JSON response (array of strings, will not be present if there are no warnings).

Example:

{
   "success":true,
   "message":"Email was sent successfully.",
   "warnings":[
      "Email integration 5b337eceeb7cdb000d4e20f3 does not exist."
   ]
}

7.: The tracking of campaign events status=open and status=click will not contain the integration_id and integration_name properties. This is due to the fact that rendering of the email that contains the click and open tracking happens before we know which integration will be used and whether fallback will happen.

Transactional Email Fallback module is turned OFF

1.: When the integrations field contains only one id, there is no change in the behaviour except using the accompanied sender_address. The integration id will be used and the attempt will succeed or fail.

2.: When the integrations field contains two ids, the first id will be used and the attempt will succeed or fail. The API response will contain a warning in the warnings field of the JSON response.

Example:

{
   "success":true,
   "message":"Email was sent successfully.",
   "warnings":[
      "Module Transactional Email Fallback is not enabled, using only first integration."
   ]
}

In case the first integration id does not point to an existing email integration the second integration id will be used even in case the module is turned off. The API response will contain a warning in the warnings field of the JSON response.

Example:

{
   "success": true, 
   "message": "Email was sent successfully.", 
   "warnings": [
      "Email integration 5b337eceeb7cdb000d4e20f3 does not exist."
   ]
}

🚧

In both behaviours when neither provided integration_id exists, the response code will be 404.

Limitations

  • Maximum size of all attachments together: 15 MB.
  • Maximum number of attachments: 10.
Language
Click Try It! to start a request and see the response here!