Welcome to the Bluecore Transactional API

Use this resource to integrate with Bluecore’s Transactional API to begin sending transactional and real-time welcome emails with Bluecore.

Bluecore recommends that a member of your IT team complete this setup, as it requires a highly technical skillset. This document covers the following areas:

• Authorization: This section describes how to authenticate with the Transactional API.
• Send Email: This section describes how to trigger transactional or real-time welcome emails for both tests and live sends.
• Get Status: This section describes how to view the status of a previously-triggered transactional or real-time welcome email campaign. If a transactional or real-time welcome email is not received when testing, this API call can be used to troubleshoot.

NOTE: You will need the previously provided API key to complete this setup. If you do not have an API key, please reach out to our Product Support team at support@bluecore.com.

NOTE: The transactional API is intended for server-to-server communication only. Calling the transactional API from a browser can expose your API token publicly. If you’ve attempted this already, you should immediately reach out to Bluecore support to cycle your API token.

The transactional API is protected by a customer-specific API key, which is provided by Bluecore. Please provide this API key with each request in the HTTP Authorization header, type Bearer.

Example request header:

Authorization: Bearer {Bluecore API Key}

Every request made requires a request body formatted in JSON containing your email’s contents and metadata.

{ 
    "campaign_id": string, 
    "email": string, 
    "template_attributes": { 
        (key: value)+ 
    }, 
    "customer_attributes": { 
        (key: value)+ 
    }, 
}

Template attributes are used to include data in the API payloads to display in the email template.

The values in template_attributes can be referenced in the email template by the corresponding key name.

Using the example payload below, the Product 1 item_desc would be displayed with the email template code {{ordered_products.0.item_desc}}.

{ 
    "campaign_id": "34545238545", 
    "email": "test@bluecore.com" 
    "template_attributes": { 
        "ordered_products": [ 
            { 
                "item": "Product 1", 
                "item_desc": "Description" 
            }, 
            { 
                "item": "Product 2", 
                "item_desc": null 
            } 
        ] 
    } 
}

NOTE: The request body must include template_attributes as an empty object even if there are no variables in the email template. Any references to key names in the email template must be included in the API payload template_attributes object. If a variable in the email template is meant to be populated in some cases but not others, the variable name for that property must still be present in the template_attributes. The value can be set to null.

Template attributes can also include full HTML content to render in emails.

{ 
    "campaign_id": "34545238545", 
    "email": "test@bluecore.com" 
    "template_attributes": { 
        "html_content": "<h2>hello test!</h2>" 
    } 
}

NOTE: When passing full HTML content in the JSON for the template attributes, Bluecore recommends the following:

• JSON must be one line.
• Strings must be delimited with ". Never with '.
• ' must never be escaped.
• Quotations ("), newlines, tabs must be escaped with only one backslash.

The customer_attributes object is used for the purpose of updating customer information in Bluecore. Only real-time welcome campaigns will result in updates to customer attributes.

NOTE: Some attributes are protected and cannot be passed as customer attributes:

• email
• created
• merged
• orphaned
• aliases

Whenever you make a request to the send endpoint, your JSON payload is validated before your email is sent. If there are any errors, Bluecore will attempt to identify and return as many issues as possible for each request. The validation additionally checks that the API payload does include all the attributes called out in the template.

• The total size of your payload must be less than 900 KB.
• Transactional API calls cannot exceed 200 calls/sec.
• Transactional or real-time welcome sends will only be sent via Bluecore. Other ESP adapters will not be supported.
• We do not currently support the following when sending transactional or real-time welcome emails:
• Bluecore powered product recommendation blocks. Use dynamic content by providing it directly into the API payload.
• Bluecore powered coupon blocks. Use dynamic content by providing it directly into the API payload.
• Only ASCII character email addresses are supported.