Send Transactional Messages (PHP)

This tutorial is intended for view on larger devices.

Email Yourself a link for later

Send Transactional Emails

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 Tutorial

Prerequisites

A 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.

  1. First, build the message you will use when sending transactional deliveries. Your message must follow the 80/20 rule: 80% of transactional information and up to 20% of promotional information. Any fielddata you use in your message must be smaller than 1 MB.
  2. Next, go to
  3. Messages->Email Messages, click on the name of the transactional message, then click Request Approval.

Authenticate With Bronto

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:

  1. Go to Home->Data Exchange.
  2. Click Add Access Token.
  3. Make sure the token has Read, Write and Send permissions.
  4. Create API Session

    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 Message ID

    Get the ID for the message that was approved for transactional sending.

    Give Contacts Transactional Status

    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.

    Make the Delivery Timestamp

    Indicate the start time for the message delivery.

    Provide Delivery Parameters

    Create an array that contains all of the delivery parameters. This should include:

    • The start time (Line 78)
    • The message ID (Line 79)
    • Your sender information (from name, from email address; Lines 80 and 81)
    • All relevant message recipients (Line 82)
    • The message type (Line 83)

    Provide Message Tag Data

    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.

    Call addDeliveries

    Use the addDeliveries call to send the transactional message to a single contact.

    Results

    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.