Blueshift's sync_render API endpoint can be used to render emails without actually executing the message send. With this endpoint, you have the ability to author your email templates in Blueshift but handle the delivery yourself. This feature is applicable only if you do not want Blueshift to run the campaign for you.
This feature is disabled by default. Contact support@blueshift.com to enable this feature for your account.
API Limitations
Consider the following limitations before you use the sync_render API endpoint:
- Templates with external fetch are not allowed. An error occurs if the template includes external fetch data. Instead, include all the required data for rendering in the API call.
- The API does not fetch the user from Blueshift. This imposes some additional limitations:
- Make sure all user attributes that you plan to use are included in your request payload.
- Recommendations are not allowed. An error occurs if the template includes recommendations.
- The email_preview_link, unsubscribe_link, and resubscribe_link Liquid variables that are normally available will not work. You will need to provide your own links to handle previews and unsubscribe/subscribe, as well as orchestrating the functionality yourself.
- Since these emails are not delivered by Blueshift, links will not get rewritten for tracking. This also means that click events on these emails will not get sent to Blueshift.
- We also do not automatically add an open pixel like we normally do. Blueshift will not receive open events for these emails.
Sending the Request
To use this endpoint, issue an HTTP Post request to https://api.getblueshift.com/api/v1/sync_render using your account's User API key to authenticate. Additionally, you should add HTTP headers for Accept and Content-type and set them to application/json.
Here is an cURL template for what the request should look like:
curl -X POST -H "Accept: application/json" -H "Content-type: application/json" -d '{
"template_uuid": <template_uuid>,
"transaction_uuid": <transaction_uuid>,
<key>: <val> ,
<another_key>: <another_val>
}' -u : https://api.getblueshift.com/api/v1/sync_render
You must include the following two required parameters with every API call:
| Parameter | Description |
| template_uuid | The UUID of the Blueshift template you want to render. |
| transaction_uuid | A UUID generated by you that should be unique for each API call. It is used to identify a specific request and used to debug any issues with the API. |
All other parameters are made available in the template for rendering. Here is what a full sample request might look like:
curl -X POST -H "Accept: application/json" -H "Content-type: application/json" -d '{
"template_uuid": "c82fedad-3cca-4a64-a814-11f00988942b",
"transaction_uuid": "2413c1fd-56b0-43bb-a5df-93c82ccdce5c",
"firstname": "John",
"lastname": "Doe",
"has_purchased": true
}' -u 6da81ea1ce35b2e8a9a65df23fb03bc4: https://api.getblueshift.com/api/v1/sync_render
Payload Limitations
You can use almost any key name you want in your payload. The only reserved key names you cannot use are action and controller.
Handling the Response
The API responds with a HTTP status code and a JSON encoded body. You should first look at the HTTP status code to determine if the request was successful, failed, or needs to be retried.
| Code | Meaning | Description |
| 200 | Success | The template was successfully rendered. |
| 400 | Bad Request | The request body was invalid. This means you are missing or have an error with the template_uuid or transaction_uuid. |
| 401/403 | Unauthorized or Forbidden | The User API key was incorrect or this feature has not been enabled for your account yet. |
| 404 | Resource not found | Can occur if an invalid API endpoint is specified. Ensure that you are using the correct URL: https://api.getblueshift.com/api/v1/sync_render. |
| 422 | Unprocessable entity | The request body was valid but the template failed to render. See below on how to handle these errors. |
| 429 | Rate limit exceeded | Too many requests, please contact Blueshift for recommended throughput. |
| 500 | Internal Server Error | An unforeseen error occurred, contact Blueshift for more information. |
| 502 | Bad Gateway | Error establishing connection, retry with exponential back-off. |
| 503 | Service Unavailable | Service is temporarily unavailable, retry with exponential back-off. |
| 504 | Gateway Timeout | The connection timed out, retry with exponential back-off. |
Success (200 HTTP Status Code)
If the template is successfully rendered, the response body includes the following:
{
"success": true,
"template_uuid": <template_uuid>,
"transaction_uuid": <transaction_uuid>,
"html_content": <HTML body of email>,
"text_content": <text version of email>,
"subject": <email subject>
}
The html_content contains minified HTML for the email. If your account has plain text emails enabled, an additional text version of the email will be set in text_context.
Error Handling
Bad Request (400 HTTP Status Code)
This response means the HTTP post request body was invalid. It can be due to a missing or invalid required parameter. You should look at the error message to see what needs to be corrected and resend your request. The response will include an original_request parameter which is set the parameters the HTTP post request was made with.
{
"success": false,
"original_request": {
"transaction_uuid": <transaction_uuid>,
<key>: <value> ,
<another_key>: <another_value>
},
"error_message": "request body missing required template_uuid"
}
Unprocessable Entity (422 HTTP Status Code)
These class of errors mean the request parameters were valid but the template rendering still failed. The response will body will contain an error code and error message detailing what went wrong. In addition, it will also include a retry flag that indicates whether or not you should retry your request. If it is set to true, you should retry with exponential back-off.
{
"success": false,
"original_request": {
"transaction_uuid": <transaction_uuid>,
"template_uuid": <template_uuid>,
<key>: <value>,
<another_key>: <another_value>
},
"error_code": 156
"error_message": "template has external fetch",
"retry": false
}
Other error codes
Here is a list of some error codes, their meanings, and whether it should retried or not. Note that the description may not match what is returned by the API.
| Error Code | Retry | Description & How to Resolve |
| 109/110 | Yes | Internal connection error. Retry your request with exponential back-off. |
| 115 | No | An error occurred when rendering the template. Usually this occurs when the template has invalid Liquid syntax. |
| 156 | No | The template uses external fetch. Remove external fetch from the template before retrying your request. |
| 160 | No | The template with the specified template_uuid was not found. Verify that you are sending the correct UUID in your request. |
| 161 | No | The template uses recommendations. Remove recommendations from the template before retrying your request. |
Comments
0 comments