One of the most common use cases for the Bronto API is sending transactional messages - most commonly, order and shipping confirmations. While these messages can be triggered with an in-house solution or a shopping cart vendor’s email tool, there are key advantages to sending them in Bronto. What follows is the sequence and description of the steps you need to implement to send transactional messages using the Bronto API.
Start TutorialA message must meet a specific set of criteria before it can be sent as a transactional message. Therefore before you can send a transactional message using the API, the message must be created and sent for transactional approval using the Bronto platform.
Once a message is approved for transactional sending, you can set up your API calls. Before you can login using the API, you need to log into Bronto and set up your authentication and API access tokens. To do this:
Use the access token you created to log in. The session ID created when you log into the API will expire if there is no transaction for a 20 minute period.
Get the ID for the message that was approved for transactional sending.
New contacts who have not opted in yet may have an onboarding status. In order for you to be able to send these contacts transactional messages, you will need to update their status to transactional for this send.
When calling addOrUpdateContacts, new contacts will be added while existing contacts will be updated. In the code example, the contact status is set to transactional. This will not update an existing contact's status, but it will allow you to send transactional emails to new contacts who have not opted-in to receive promotional/marketing emails.
if the contact is on the suppression list, the errorCode 315 or errorString EMAIL_SUPPRESSED will be returned in the result array. If the contact is on the suppression list, he/she will not receive any email, including transactional emails. If the contact has a status of inactive or unsubscribed, he/she will still receive transactional emails.
Indicate the start time for the message delivery.
Create an array that contains all of the delivery parameters. This should include:
Tags are unique variables in a messages that can be replaced by data passed in via the API. In the case of a transactional message, this can be very handy when passing multiple items such as line items included in the shopping cart. If there are tags in a message, you need to provide the appropriate data for each tag in your code. In this example, lines 90 - 95 demonstrate how to provide data for a loop that contains three API message tags that represent items included in a shopping cart. In the email the example loop would look similar to
{dynamic_code}{loop} %%#productname_1%% %%#productprice_1%% %%#productname_2%% %%#productprice_2%% %%#productname_3%% %%#productprice_3%% {/loop}{/dynamic_code}with each field separated by a break. While the tag in the message contains %%#%%, you should not include these in your code.
Use the addDeliveries call to send the transactional message to a single contact.
After you send the message you will receive a confirmation or error message. In the event of an error, we suggest you retry connecting to the API a few times before exiting your script, and saving in an error log when the failure happened.
In order to retrieve all objects in a result set, you must iterate over all the available pages. This is done by incrementing the pageNumber parameter on subsequent read calls. When the API returns an empty result set, you know that you have retrieved all objects available. The initial page number is 1. The behavior of making multiple read calls to the same page is not defined and should not be relied upon to perform successfully.