API Message Tags

API Message tags allow you to include data stored outside of Bronto in your messages when you send messages using the API.

API message tags are user defined tags that allow you to insert HTML content into the body and subject line of messages using the API. The content you add via API message tags will be added to the message at send time. These tags are useful if you want to sync content from your system (database, CRM, etc.) with messages you send with the platform. You will need to call addDeliveries in order to use API message tags.

The syntax for creating an API message tag is %%#userdefined%%, where userdefined can be anything you want it to be. As part of the addDeliveries call you will map the appropriate content for each tag you define. You will need to use a slightly different syntax when using API message tags within loop tags. For more information on using API message tags within loop tags, see API Loop Tags.

You can use API tags within dynamic code to achieve more complex results than just simply passing a value into Bronto. For example, you could use if else conditional tags to display different content in a message based on which conditional is met. For more information see Dynamic Code and Dynamic Code Tags.

Warning: The userdefined portion of API message tags cannot contain underscores followed by a number (tag_9), or number/hash symbols (#). Underscores followed by text are permitted (tag_name).

For example tags in your message

might look like this after content is passed in using the API

Here is an example of what the addDeliveries call for that message might look like:



<?php
/**
 * API VERSION 4
 * This example will create a delivery to send a message to a single
 * contact. It assumes you have already created a message containing
 * the following API messages tags: %%#purchasetable%% and
 * %%#cardlast4%%.
 **/

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

try {
	// Replace with a valid API token
	$token = "INSERT A VALID API TOKEN";

	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 may be more
	// efficient to hardcode the ID here, depending on your own
	// usage scenario(s).
	// Replace the placeholder text with the name of a message
	// in you account.

	$messageFilter = array('name' => array('operator' => 'EqualTo',
										   'value' => 'SOME MESSAGE NAME',
										   ),
						   );
	$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 may be
	// more efficient to hardcode the ID here, depending on your
	// own usage scenario(s).
	// Replace the placeholder text with the email address
	// of the contact you want to send to.

	$contactFilter = array('email' => array('operator' => 'EqualTo',
											'value' => 'SOME EMAIL ADDRESS'
											),
						   );
	$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');

	$recipientObject = array('type' => 'contact',
							 'id' => $contact->id);

	// Create an array of delivery parameters including the content
	// which will be displayed in place of the API message tags.
	// Replace the placeholder text for the from name and from
	// email address.

	$delivery = array();
	$delivery['start'] = $now;
	$delivery['messageId'] = $message->id;
	$delivery['fromName'] = 'EXAMPLE FROM NAME';
	$delivery['fromEmail'] = 'EXAMPLE FROM EMAIL ADDRESS';
	$delivery['recipients'] = array($recipientObject);

	// If the contact prefers HTML, they will receive the content below:

	$delivery['fields'][] = array('name' => 'purchasetable', 'type' => 'html', 'content' => '<table border="1px"><tbody><tr><th>Item</th><th>Quantity</th><th>Price</th></tr><tr><td>Soccer Ball</td><td>3</td><td>123.87</td></tr></tbody></table>');
	$delivery['fields'][] = array('name' => 'cardlast4', 'type' => 'html', 'content' => '7239');

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

			

For another example of using API message tags, see Transactional Emails.

Tip:
You can pass in an entire link via a field tag or API message tag. For example, you could pass in:
<a href="%%sometag%%">My Site</a>
This link will be tracked. When viewing a click report for the message or delivery, the links created using field tags or API message tags (and their associated metrics) will appear in the grid showing link level metrics as All Dynamic Links.
Dynamic Link Tracking