/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 or our support. 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 type

Permissions needed

Private access

Campaigns > Transactional email API

Read more about:

Path parameters

Parameter

Type

Description

Required

projectToken

string

The ID of your project.

Required

Body Parameters

Parameter

Type

Description

Required

integration_id

string

The ID of your Email Service Provider 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.

integrations

Object (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_content

object

Define 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_name

string

The name of the email campaign.

Required

recipient

object

Define the recipients of this email.

Required

transfer_identity

string

Whether 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

settings

object

JSON 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 behaviour

The default behaviour 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

Parameter

Type

Description

Required

template_id

string

The ID of the email template that you wish to send out.

Required

sender_address

string

The email address of the sender.

No

sender_name

string

This is usually a first name of sender.

No

params

object

Provide all the required data for email personalization used in the template. Format: "param_name":"value".

For example:
"first_name":"Marian"

No

attachments

json

Specify 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

(2) Through raw HTML

Parameter

Type

Description

Required

html

string

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

Jinja is not evaluated in this field.

Required

subject

string

Define the email subject.

Jinja is not evaluated in this field.

Required

sender_address

string

The email address of the sender.

Required

sender_name

string

This is usually a first name of sender.

Required

attachments

json

Specify 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

Parameter

Type

Description

Required

email

string

Specify 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_ids

string

Specify the customers that should receive your email.

You can use any type of a customer ID. Common examples would include registered or email.

Required

language

string

Language 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.

Parameter

Type

Description

Required

custom_event_properties

object

JSON object containing custom attributes in the following (name:value) format:
{
”: “
}
Name and value can be a string or number.

Optional

custom_headers

object

JSON object containing request headers that will be sent to the email provider. Format:
{
”: “
}
Name and value can be a string or number.

Optional

url_params

object

JSON 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_identity

string

Whether link transfer ability should be enabled. Possible values:

  1. enabled - default value;
  2. disabled;
  3. iitt - do not transfer identity into the link

This setting is the same as the transfer_identity 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

Integrations object parameters

Parameter

Type

Description

Required

id

string

The ID of the Email Service Provider integration.

Required

sender_address

string

Email address that will be used as the email's sender for this integration, overriding any other ways of supplying this parameter.

Required

Header

Parameter

Type

Description

Required

authorization

string

Used for authentication. Read more in the Authentication section.

Required

content-type

string

application/json

Required

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"
}

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!