addDeliveries

Overview

The addDeliveries function allows you to add a new delivery/deliveries along with data associated with the delivery. Note: The addDeliveries function will return a delivery ID. Please wait a few mintues before attempting to read delivery data (readDeliveries) using the returned delviery ID. 

Syntax

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

Required and Optional Delivery Attributes

Name Type Required Description
start dateTime Yes 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.
messageId string Yes The id of the message associated with the delivery.
type string No

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 test delivery 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 Yes The email address used as the Reply-To Address for the delivery.
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.

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.
authentication boolean No; default is false 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 clicked the Allow API to select sending options checkbox via the application UI on step 2 of creating an API triggered automated message rule.
replyTracking boolean No; default is false 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 clicked the Allow API to select sending options checkbox via the application UI on step 2 of creating an API triggered automated message rule.

Examples

Examples

<?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;
	}

	// make delivery start timestamp
	$now = date('c');

	$deliveryRecipientObject = array('type' => 'contact',
					'id' => $contact->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->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);
}
/**
 * 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 = "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 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;
	}

	// make delivery start timestamp
	$now = date('c');

	$deliveryRecipientObject = array('type' => 'contact',
					'id' => $contact->id);
/*
Create an array of delivery parameters including the content
which will be displayed by the loop tags added in the example
message.
*/						
$delivery = array();
$delivery['start'] = $now;				
$delivery['messageId'] = $message->id;
$delivery['fromName'] = 'API Robot';
$delivery['fromEmail'] = 'api_test@example.com';
$delivery['recipients'] = array(deliveryRecipientObject);
/*
Notice below that when you reference the name of the loop tag via the API, 
be sure to leave of the "%%# _#%%" portion of the tag. You will build 
an array using individual API message tags which are named 
as follows: <basename>_<number>. For example, name => item_1, rather 
than name => %%#item_#%%.
*/ 
$delivery['fields'][] = array('name' => 'productname_1', 'type' => 'html', 'content' => 'A Cool Shirt');
$delivery['fields'][] = array('name' => 'productname_2', 'type' => 'html', 'content' => 'Some Nice Shoes');
$delivery['fields'][] = array('name' => 'productname_3', 'type' => 'html', 'content' => 'A Trendy Hat');
$delivery['fields'][] = array('name' => 'productprice_1', 'type' => 'html', 'content' => '$20.99');
$delivery['fields'][] = array('name' => 'productprice_2', 'type' => 'html', 'content' => '$50.99');
$delivery['fields'][] = array('name' => 'productprice_3', 'type' => 'html', 'content' => 'FREE!'); 
$deliveries[] = $delivery;

        $parameters = array('deliveries' => $deliveries);
        $res = $client->addDeliveries($parameters)->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);
}
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()
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()