addDeliveries

The addDeliveries function allows you to add a new delivery/deliveries along with data associated with the delivery.

Overview

The addDeliveries function will return a delivery ID. Please wait a few minutes before attempting to read delivery data (readDeliveries). The returned Delivery ID is an aggregate ID and not associated with individual contacts. It cannot be used as a parameter for deliveryFilter.

Note:

Links included in the content of a messageFieldObject are considered dynamic links. Static links are links that are included in the message content. Bronto will track up to 30 dynamic links added via the API for single send messages and up to 10 links for bulk messages.

Syntax

writeResult = bApi.addDeliveries(deliveryObject[] deliveries);

Attributes

Name Type Required Description
start dateTime Required for bulk sends only; optional for single sends. The date the delivery was scheduled to be sent. You can (and should) specify a timezone offset if you do not want the system to assume you are providing a time in UTC (Universal Coordinated Time / Greenwich Mean Time). For the Eastern Time Zone on Daylight Savings Time, this would be YYYY-MM-DDTHH:MM:SS-04:00. For single contact sends, start is not required. For single sends, the date must be within two years of the current date.
messageId string Yes The id of the message associated with the delivery. You must reference the message you want to use in the delivery by ID. We do not support passing in a messageContentObject when using addDeliveries.
type string Yes The type of delivery. Valid values are:
  • triggered
  • test
  • transactional.

triggered is the default. Only use transactional when adding a delivery which uses a message that has been approved for transactional sending.

Note: If you attempt to send a triggered or testdelivery to a contact with a status of transactional, the delivery will be set to skipped and the delivery will not be sent.
fromEmail string Yes The email address used in the From Address for this delivery.
fromName string Yes The name used as the From Name for the delivery
replyEmail string No The email address used as the Reply-To Address for the delivery. If no replyEmail is provided, the fromEmail will be used.
authentication boolean No Enables sender authentication for the delivery if set to true. Sender authentication will sign your message with DomainKeys/DKIM (an authentication method that can optimize your message delivery to Hotmail, MSN, and Yahoo! email addresses). If you are associating this delivery with an automated message rule, these parameters will only be accepted if you checked the Allow API to select sending options box via the application UI on step 2 of creating an API triggered automated message rule.
replyTracking boolean No Enables reply tracking for the delivery if set to true. Enabling Reply Tracking will store a copy of all replies to your messages on the Replies page. You may find this option convenient if you need someone other than the email address in the From line to read replies, or simply want the application to store replies. If you are associating this delivery with an automated message rule, these parameters will only be accepted if you checked the Allow API to select sending options box via the platform when creating an API triggered automated message rule.
messageRuleId string No The ID of an automated message rule to associate with this delivery. Used to include this delivery in the reporting for the automator you specify.
optin boolean No; default is false Whether or not this delivery is an opt-in confirmation email. If set to true, contacts who have not yet confirmed their opt-in status with the account will still receive the message.
throttle long No Allows you to specify a throttle rate for the delivery. Throttle rate must be in range [0, 720] (minutes). For example you could specify 60 for the throttle range.
Note: Throttling slows your email delivery speed, and thus spreads your email deliveries out over time. Many major ISPs track a sender’s reputation based on the number of unsolicited email complaints that they generate over a certain period of time. The worse your sender reputation is with ISPs, the more likely you are to have a low sender rating in the application. Spreading your email delivery over time can help mitigate the impact of this issue, help ensure optimal deliverability, and mitigate traffic spikes on your website.
fatigueOverride boolean No If set to true, the delivery can be sent even if it exceeds frequency cap settings for a contact.
remail remailObject[] No A remail object. Remails allow you to send another email to contacts based on actions they did not take. The goal is to persuade them to continue along the conversion process.
recipients deliveryRecipientObject[] Yes An array of the recipients who were or are scheduled to receive the delivery. Recipients can include lists, segments, or individual contacts.
fields messageFieldObject[] No; default is none An array of the API fields and data to substitute into the message being sent by this delivery.
products deliveryProductObject[] No; default is none Specifies Product IDs to substitute for placeholders in product tags upon message send. Limit: 100 products
cartId string No The ID of a shopping cart you want to associate with this delivery.
orderId string No The Bronto-provided ID for an order you want to associate with this delivery.

Example Response

stdClass Object
(
    [results] => Array
        (
            [0] => stdClass Object
                (
                    [id] => 372015ba-7c48-4ff5-ad5c-297d4beaff6z

                    [isNew] => 1
                    [isError] =>
                    [errorCode] => 0
                )

        )

)

PHP Code Example For Single Delivery

  <?php
/**
      * This example will create a delivery to send a message to a single contact.
      * You must edit the code to refer to the message name you wish to send, 
      * and change the email address of the contact to be a valid contact in 
      * your account.
      */
 
      $client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1, 
            'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
      setlocale(LC_ALL, 'en_US');
 
      try {
        $token = "YOUR_TOKEN_HERE";
 
        print "logging in\n";
        $sessionId = $client->login(array('apiToken' => $token))->return;
 
        $session_header = new SoapHeader("http://api.bronto.com/v4",
                'sessionHeader',
                array('sessionId' => $sessionId));
        $client->__setSoapHeaders(array($session_header));
 
        // get the id of the message you wish to send.  It would be more
        // efficient to hardcode the ID here, and you may choose to do that 
              // based on your own usage scenario(s).
        $messageFilter = array('name' => array('operator' => 'EqualTo',
                   'value' => 'NAME OF YOUR MESSAGE HERE')
                                     );
        $message = $client->readMessages(array('pageNumber' => 1,
                'includeContent' => false,
                'filter' => $messageFilter)
                )->return[0];
        if (!$message) {
          print "There was an error retrieving your message.\n";
                      exit;
        }
 
        // get the id of the contact you will be sending to.  It would be
        // more efficient to hardcode the ID here, and you may choose to do that
        // based on your own usage scenario(s).
 
              $contactFilter = array('email' => array('operator' => 'EqualTo',
                'value' => 'RECIPIENT_EMAIL@EXAMPLE.COM'
                ),);
        $contact = $client->readContacts(array('pageNumber' => 1,
                  'includeLists' => false,
                  'filter' => $contactFilter)
                )->return[0];
        if (!$contact) {
          print "There was an error retrieving your contact.\n";
          exit;
        }
 
        $deliveryRecipientObject = array('type' => 'contact',
                'id' => $contact->id);
 
        $delivery = array('messageId' => $message->id,
            'fromName' => 'Bronto API Robot',
            'fromEmail' => 'bronto_api_test@example.com',
            'recipients' => array($deliveryRecipientObject),
                           );
          $res = $client->addDeliveries(array($delivery))->return;
          if ($res->errors) {
              print "There was a problem scheduling your delivery:\n";
              print $res->results[$res->errors[0]]->errorString . "\n";
          } else {  
              print "Delivery has been scheduled.  Id: " . $res->results[0]->id . "\n";
          }
      } catch (Exception $e) {
          print "uncaught exception\n";
          print_r($e);
      }

PHP Code Example For Bulk Delivery

<?php
/**
      * This example will create a delivery to send a message to a list using readLists
      * to retrieve the list id. You must edit the code to refer to the message name you
      * wish to send, and change the list name to be a valid list in your account.
      */
 
      $client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1,
            'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
      setlocale(LC_ALL, 'en_US');
 
      try {
        $token = "ADD YOUR API TOKEN HERE";
 
        print "logging in\n";
        $sessionId = $client->login(array('apiToken' => $token))->return;
 
        $session_header = new SoapHeader("http://api.bronto.com/v4",
                'sessionHeader',
                array('sessionId' => $sessionId));
        $client->__setSoapHeaders(array($session_header));
 
        // Get the id of the message you wish to send.  It would be more
        // efficient to hardcode the ID here, and you may choose to do that
        // based on your own usage scenario(s).
        $messageFilter = array('name' => array('operator' => 'EqualTo',
                   'value' => 'NAME OF YOUR MESSAGE HERE')
                                     );
        $message = $client->readMessages(array('pageNumber' => 1,
                'includeContent' => false,
                'filter' => $messageFilter)
                )->return[0];
        if (!$message) {
          print "There was an error retrieving your message.\n";
                      exit;
        }
 
        // get the id of the list you will be sending to.  It would be
        // more efficient to hardcode the ID here, and you may choose to do that
        // based on your own usage scenario(s). You can use segmentFilter
        // instead here if you are sending to a segment.
        $listFilter = array('name' => array('operator' => 'EqualTo',
                'value' => 'NAME OF YOUR LIST HERE'
                ));
 
        $list = $client->readLists(array('pageNumber' => 1,
                  'includeLists' => false,
                  'filter' => $listFilter)
                )->return[0];
        if (!$list) {
          print "There was an error retrieving your list.\n";
          exit;
        }
 
        // make delivery start timestamp
        $now = date('c');
 
        $deliveryRecipientObject = array('type' => 'list',
                'id' => $list->id);
 
        $delivery = array('start' => $now,
            'messageId' => $message->id,
            'fromName' => 'Bronto API Robot',
            'fromEmail' => 'bronto_api_test@example.com',
            'recipients' => array($deliveryRecipientObject),
                           );
          $res = $client->addDeliveries(array($delivery))->return;
 
          if ($res->results[0]->isError) {
              print "There was a problem scheduling your delivery:\n";
              print $res->results[0]->errorString . "\n";
          } else {
              print "Delivery has been scheduled.  Id: " . $res->results[0]->id . "\n";
          }
      } catch (Exception $e) {
          print "uncaught exception\n";
          print_r($e);
      }

Python Code Example

import sys
import logging
from suds.client import Client
from suds import WebFault
from datetime import datetime
 
 
# This example script will login in to the API, obtain
# a message ID and contact ID, and use those IDs to
# send the message to the contact. 
 
# BE SURE TO REPLACE ALL PLACEHOLDER TEXT
 
# Tested with Python 2.6.1 and suds soap library version 0.4
 
# See suds home page:
# https://fedorahosted.org/suds/
 
 
 
# Bronto API WSDL
BRONTO_WSDL = 'https://api.bronto.com/v4?wsdl'
 
# Start up basic logging
logging.basicConfig()
 
# Replace the placeholder text with a valid
# API token
TOKEN = "API TOKEN HERE"
 
 
# Login using the token to obtain a session ID
bApi = Client( BRONTO_WSDL )
 
try:
  session_id = bApi.service.login(TOKEN)
# Just exit if something goes wrong
except WebFault, e:
   print '\nERROR MESSAGE:'
   print e
   sys.exit()
 
# Set up the soap headers using the
# session_id obtained from login()
session_header = bApi.factory.create("sessionHeader")
session_header.sessionId = session_id
bApi.set_options(soapheaders=session_header)
 
# Get the ID of the message you wish to 
# send by calling readMessages.
# Be sure to replace the placeholder text below  
 
messageFilter = bApi.factory.create('messageFilter')
 
message_name = bApi.factory.create('stringValue')
filter_operator = bApi.factory.create('filterOperator')
message_name.operator = filter_operator.EqualTo
message_name.value = 'SOME MESSAGE NAME'
messageFilter.name = message_name
 
filterType = bApi.factory.create('filterType')
messageFilter.type = filterType.AND
 
try:
  read_message = bApi.service.readMessages(messageFilter, includeContent = False, pageNumber = 1)
  print 'The id for the message: ' + read_message[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()
 
# Get the ID of the contact you wish to send
# to by calling readContacts,
# Be sure to replace the placeholder text below  
filter = bApi.factory.create('contactFilter')
 
stringValue = bApi.factory.create('stringValue')
stringValue.value = 'SOME EMAIL ADDRESS'
filterOperator = bApi.factory.create('filterOperator')
stringValue.operator = filterOperator.EqualTo
 
filterType = bApi.factory.create('filterType')
 
filter.email = stringValue
filter.type = filterType.AND
 
try:
  read_contact = bApi.service.readContacts(filter, includeLists = True, pageNumber = 1)
  print 'Contact ID: ' + read_contact[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()
 
# Get the current date and time so we can send the 
# email message now  
sendtime = datetime.now()
 
# Call addDeliveries using the send time, message ID, and 
# contact ID specified above.
# Be sure to replace the placeholder text below  
 
add_delivery = bApi.factory.create('deliveryObject')
add_delivery.start = sendtime
add_delivery.messageId = read_message[0].id
add_delivery.fromName = 'SOME FROM NAME'
add_delivery.fromEmail = 'SOME FROM EMAIL ADDRESS'
 
deliveryRecipientObject = bApi.factory.create('deliveryRecipientObject')
deliveryRecipientObject.type = 'contact'
deliveryRecipientObject.id = read_contact[0].id
add_delivery.recipients = deliveryRecipientObject
 
try:
  delivery = bApi.service.addDeliveries(add_delivery)
  if delivery.results[0].isError == True:
    print 'There was an error with your request:'
    print delivery.results[0]
    sys.exit()
  else:
    print 'The delivery has been sent. The delivery ID is: ' + delivery.results[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()

Python Code Example With Loop Tags

import sys
import logging
from suds.client import Client
from suds import WebFault
from datetime import datetime
 
 
# This example script will login in to the API, obtain
# a message ID and contact ID, and use those IDs to
# send the message to the contact. This script assumes
# the email message being sent contains {loop}{/loop}
# tags and the following the API message tags contained 
# within the loop tags: 
# %%#productname_#%%
# %%#productprice_#%%
 
# BE SURE TO REPLACE ALL PLACEHOLDER TEXT
 
# Tested with Python 2.6.1 and suds soap library version 0.4
 
# See suds home page:
# https://fedorahosted.org/suds/
 
 
 
# Bronto API WSDL
BRONTO_WSDL = 'https://api.bronto.com/v4?wsdl'
 
# Start up basic logging
logging.basicConfig()
 
# Replace the placeholder text with a valid
# API token
TOKEN = "ADD API TOKEN HERE"
 
 
# Login using the token to obtain a session ID
bApi = Client( BRONTO_WSDL )
 
try:
  session_id = bApi.service.login(TOKEN)
# Just exit if something goes wrong
except WebFault, e:
   print '\nERROR MESSAGE:'
   print e
   sys.exit()
 
# Set up the soap headers using the
# session_id obtained from login()
session_header = bApi.factory.create("sessionHeader")
session_header.sessionId = session_id
bApi.set_options(soapheaders=session_header)
 
# Get the ID of the message you wish to 
# send by calling readMessages.
# Make sure the message contains {loop}{/loop}
# tags and the following the API message tags contained 
# within the loop tags: 
#     %%#productname_#%%
#     %%#productprice_#%%
# Be sure to replace the placeholder text below  
 
messageFilter = bApi.factory.create('messageFilter')
 
message_name = bApi.factory.create('stringValue')
filter_operator = bApi.factory.create('filterOperator')
message_name.operator = filter_operator.EqualTo
message_name.value = 'SOME MESSAGE NAME'
messageFilter.name = message_name
 
filterType = bApi.factory.create('filterType')
messageFilter.type = filterType.AND
 
try:
  read_message = bApi.service.readMessages(messageFilter, includeContent = False, pageNumber = 1)
  print 'The id for the message: ' + read_message[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()
 
# Get the ID of the contact you wish to send
# to by calling readContacts,
# Be sure to replace the placeholder text below  
filter = bApi.factory.create('contactFilter')
 
stringValue = bApi.factory.create('stringValue')
stringValue.value = 'SOME EMAIL ADDRESS'
filterOperator = bApi.factory.create('filterOperator')
stringValue.operator = filterOperator.EqualTo
 
filterType = bApi.factory.create('filterType')
 
filter.email = stringValue
filter.type = filterType.AND
 
try:
  read_contact = bApi.service.readContacts(filter, includeLists = True, pageNumber = 1)
  print 'Contact ID: ' + read_contact[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()
 
# Get the current date and time so we can send the 
# email message now  
sendtime = datetime.now()
 
# Call addDeliveries using the send time, message ID, and 
# contact ID specified above.
# Be sure to replace the placeholder text below  
 
add_delivery = bApi.factory.create('deliveryObject')
add_delivery.start = sendtime
add_delivery.messageId = read_message[0].id
add_delivery.fromName = 'SOME FROM NAME'
add_delivery.fromEmail = 'SOME FROM EXAMPLE'
 
deliveryRecipientObject = bApi.factory.create('deliveryRecipientObject')
deliveryRecipientObject.type = 'contact'
deliveryRecipientObject.id = read_contact[0].id
add_delivery.recipients = deliveryRecipientObject
 
fieldObject = bApi.factory.create('messageFieldObject')
 
add_delivery.fields = fieldObject
 
# Create a fieldObject list of each
# fieldName and fieldPrice
fieldObject = []
 
# For each fieldName and fieldPrice, create
# a dictionary containing a name, type, and content, and
# then append that dicitionary to the fieldObject list.
 
fieldName0 = {}
fieldName0['name'] = 'productname_0'
fieldName0['type'] =  'html'
fieldName0['content'] =  'A Cool Shirt'
fieldObject.append(fieldName0)
 
fieldName1 = {}
fieldName1['name'] = 'productname_1'
fieldName1['type'] = 'html'
fieldName1['content'] = 'Some Nice Shoes'
fieldObject.append(fieldName1)
 
fieldName2 = {}
fieldName2['name'] = 'productname_2'
fieldName2['type'] = 'html'
fieldName2['content'] = 'A Trendy Hat'
fieldObject.append(fieldName2)
 
fieldPrice0 = {}
fieldPrice0['name'] = 'productprice_0'
fieldPrice0['type'] = 'html'
fieldPrice0['content'] = '20.99'
fieldObject.append(fieldPrice0)
 
fieldPrice1 = {}
fieldPrice1['name'] = 'productprice_1'
fieldPrice1['type'] = 'html'
fieldPrice1['content'] = '50.99'
fieldObject.append(fieldPrice1)
 
fieldPrice2 = {}
fieldPrice2['name'] = 'productprice_2'
fieldPrice2['type'] = 'html'
fieldPrice2['content'] = 'FREE'
fieldObject.append(fieldPrice2)
 
 
 
add_delivery.fields = fieldObject
 
 
try:
  delivery = bApi.service.addDeliveries(add_delivery)
  if delivery.results[0].isError == True:
    print 'There was an error with your request:'
    print delivery.results[0]
    sys.exit()
  else:
    print 'The delivery has been sent. The delivery ID is: ' + delivery.results[0].id
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()