Synchronous Rendering Endpoint for Emails

API Overview



Error Handling

API Overview

Blueshift exposes an API endpoint that can 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 execute the campaign for you. This feature is disabled by default - talk to your Blueshift account admin to have it enabled.

API Limitations

  • Templates with external fetch are not allowed - the API will throw an error. Instead, you should include all data needed 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. The API will throw an error if the template has 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, you issue a HTTP Post request to using your account's users API key to authenticate. In addition, 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 :

There are two required parameters that you must include 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 will respond 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 transaction_uuid or transaction_uuid.
401/403 Unauthorized/Forbidden The user API key was incorrect or this feature has not been enabled for your account yet.
404 Resource not found Can happen if you specify an invalid API endpoint. Double check 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's.
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 will include 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

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. You should retry your request with exponential back-off.
115 No There was an error rendering the template. Usually this occurs when the template has invalid Liquid syntax.
156 No The template was using external fetch. Remove external fetch from the template before retrying your request.
160 No The template with the specified template_uuid was not found. Double check the uuid you are sending in your request.
161 No The template was using 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.