Send Transactional Messages Using The API

About this task

The optimal way to send transactional messages via the API is to use the addDeliveries call.

Warning: If you are using API version 3, you will need to follow the instructions for Send Transactional Messages Using Automated Message Rules And The API.

To send transactional messages via the API:


  1. Create an email message in the application.
    This email message acts as a template for the transactional email. The data relevant to the contact receiving the email is passed in using field tags (%%field%%), special tags (%%!field%%), API message tags (%%#field%%), and/or loop tags (%%#data_#%%).

    If you plan on asking the contact to opt-in to marketing communication, the message should include a manage preferences link. If you are using a previously sent email, or if you wish to make a test delivery prior to using the email as a transactional message with the API, the application assumes the message is a bulk/marketing email and automatically appends an unsubscribe link.

    To remove this link, re-save the message in the application prior to using the email for transactional deliveries. This removes any automatically appended links until the next delivery from inside the application.
    Note: After the email is re-saved, the unsubscribe link will continue to appear in the message preview but will not be included when the message is sent.
    For more information on creating email messages, see Creating an Email Message Using the WYSIWYG Editor. For more information on each type of tag that can be used in transactional messages, see the following help topics:

    Example use of API message tags

    Example content passed in from the API after the message is sent

  2. Request transactional approval for the email message.
    For more information on getting an email message approved for transactional sending, see Request Transactional Message Approval.
  3. Make an API call to send the transactional message you created.
    The example script below will obtain the ID for a contact and the ID for an email message, and then use those IDs to send the email to the contact.
      * For use with API Version 4:
      * This script will add a delivery. It will obtain of a message and a
      * a contact ID. It will use these IDs in the addDeliveries call to send
      * the appropriate transactional message to a single contact.
      * @copyright  Copyright (c) 2012 Bronto Software (
    $client = new SoapClient('',
                              array('trace' => 1,
    								'features' => SOAP_SINGLE_ELEMENT_ARRAYS)
    setlocale(LC_ALL, 'en_US');
    try {
    	// Add API token here
    	$token = "YOUR_TOKEN_HERE";
    	print "logging in\n";
    	$sessionId = $client->login(array('apiToken' => $token))->return;
    	$session_header = new SoapHeader("",
    									 array('sessionId' => $sessionId));
    	// Get the id of the contact you will be sending to. It would be
    	// more efficient to hard-code the ID here, and you may choose to do that
    	// based on your own usage scenario(s).
    	$contactFilter = array('email' => array('operator' => 'EqualTo',
    											'value' => 'CONTACT EMAIL HERE'
    	$contact = $client->readContacts(array('pageNumber' => 1,
    											'includeLists' => false,
    											'filter' => $contactFilter))->return[0];
    	if (!$contact) {
    		print "There was an error retrieving your contact.\n";
    	// Get the id of the message you will use in the delivery. It would be more
    	// efficient to hard-code the ID here, and you may choose to do that
    	// based on your own usage scenario(s).
    	$filter = array('name' => array('operator' => 'EqualTo',
    									'value' => 'MESSAGE NAME HERE')
    	$message = $client->readMessages(array('pageNumber' => 1,
    											'includeContent' => false,
    											'filter' => $filter))->return[0];
    	if (!$message) {
    		print "There was an error retrieving the message ID.\n";
    	// Make the delivery start timestamp. For this example,
    	// we will send the delivery now.
    	$now = date('c');
    	$recipientObject = array('type' => 'contact',
    							 'id' => $contact->id);
    	// Be sure to change the generic fromName and fromEmail
    	// used below!
    	$delivery = array('start' => $now,
    					  'messageId' => $message->id,
    					  'fromName' => 'API Robot',
    					  'fromEmail' => '',
    					  'recipients' => array($recipientObject),
    					  'type' => 'transactional'
    	$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";
    Note: In order to make API calls using version 4 of the API, you will need an API token. For more information on creating API tokens, see Set Up/Edit SOAP API Access Tokens.

    To view an example use off addDeliveries where API message tags and loop tags are used, see API Message Tags and API Loop Tags.

    Tip: The following functions were used in the above code example. Click on the names to read more information about each API call.