Synchronous Rendering Endpoint for Emails

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 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 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 :

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:

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:
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.
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.