/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 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. 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. |
| 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 recipient 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_identitydefault behaviorThe 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.
- Using Bloomreach Engagement template: Create an email template in Bloomreach Engagement and then send it through API.
- 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. This can be found in the URL when you go to the selected predefined template. | 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 attachmentcontent: 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
| 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 attachmentcontent: Encoded content of your file (base64)content_type: The format of your attachments | No |
Either the
template_idor a combination ofhtmlandsubjectare required. You cannot use both at the same time.
Recipient object parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
| 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 customer that should receive your email. You can use any type of 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 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_category | string | Specify the consent category of the customer if you wish to respect the consent in the Engagement platform (more info). | Optional |
| consent_category_tracking | string | Specify 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
| 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"
}
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_nameorevent.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_idexists, the response code will be 404.
Limitations
- Maximum size of all attachments together: 15 MB.
- Maximum number of attachments: 10.