Adding Email Deliveries With API V4

There are a lot of cool things you can do with version 4 of our API. Outside of the neat custom things that can be done, lies the core functionality of the API. Of these core functions is the ability to send email. In this post, I'll go over how to send email using version 4 of our API, and provide some example code to help you get started.

Getting Started

At a really high level, there is certain information that needs to be provided in order for you to properly send email via the API. Basically, the addDeliveries function needs to know when to send the email, who to send it to, from whom the email is being sent, and which content to use for the body of the email. In terms of code, the function needs to know the start, messageId, fromName, fromEmail, and recipients. More on that below.

More Than Just addDeliveries

In the code example below, I am going to use several functions to help us define which message content to use, and who to send the email to. I'll be calling readMessages and readLists respectively. readMessages will allow me to obtain a message ID so that I can specify which message to use in the delivery. readLists will allow me to obtain a list ID so that I can specify which list to send the message to.

Code Away!

There are a lot of ways you can customize the code example below, such as using a segment for the recipient object rather than a list, or modifying the start date to be a time in the future. For now though, we'll keep the script pretty basic so you can get the hang of things.

<?php
/**
 * This example will create a delivery to send a message to a list.
 * You must edit the code to use a valid API token, refer to
 * the name of the message you wish to use in the delivery,
 * change the name of the list to be a valid list in your
 * account, and use a valid from name and email address for
 * the delivery.
 */

$client = new SoapClient('https://api.bronto.com/v4?wsdl', array('trace' => 1,
													'features' => SOAP_SINGLE_ELEMENT_ARRAYS));
setlocale(LC_ALL, 'en_US');

try {
    // Replace with a valid API token
	$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.
	$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.
	$listFilter = array('name' => array('operator' => 'EqualTo',
											'value' => 'SOME LIST NAME'
											),
						   );
	$list = $client->readLists(array('pageNumber' => 1,
									 'filter' => $listFilter)
									 )->return[0];
	if (!$list) {
		print "There was an error retrieving your list.\n";
		exit;
	}

	// Make delivery start timestamp: Now
	$now = date('c');

    // Use the list ID obtained above for the recipientObject
	$recipientObject = array('type' => 'list',
							 'id' => $list->id);

    // You'll need to replace the generic text used for the from
    // name and from email address.
	$delivery = array('start' => $now,
					  'messageId' => $message->id,
					  'fromName' => 'NEW FROM NAME',
					  'fromEmail' => 'NEW FROM EMAIL',
					  'recipients' => array($recipientObject),
					  );

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

Hopefully this blog post and the accompanying code example will you get you started on your way to sending emails with API v4. If you have any questions, feel free to leave them in the comments section below.

John Gunther
Technical Writer/eLearning Specialist at Bronto
Editor of Brontoversity