API Loop Tags

API loop tags allow you to use the Bronto API to add an array of content to a message.

API loop tags are specially formatted API message tags that allow content to be passed in via API Message tags as an array. This an especially useful feature to use with transactional email messages. For example, if you are using transactional email messages to send receipts and you need to send back a receipt containing multiple purchases (say if a contact purchases more than one item from you during a single visit), you can use loop tags to create an array containing the relevant receipt information for each item purchased.

Warning: loop tags are an advanced feature and require comfort with dynamic code, programming, and the use of our API.
Note: loop tags can only be used in the body of email messages. loop tags placed in the subject line of email messages will not work.
Tip: For more information on API message tags, see API Message Tags.

Below is an example of loop tags used in the context of transactional email messages.

To make use of loop tags:

  1. Add {dynamic_code}{loop}{/loop}{/dynamic_code} tags to an email message as shown below. Notice the %%#item_#%% portion of the code. This a modified API Message Tag used specifically in loop tags.
    
    {dynamic_code}
    {loop}
    %%#item_#%%
    {/loop}
    {/dynamic_code}
    					
    Loop Tags In A Message
    Tip: In the example above, notice how the dynamic code and loop tags have been placed inside of an HTML table. This was done so the content brought in via the loop tags will display nicely in a table. It is perfectly ok to do this, but you will need to TURN OFF the WYSIWYG editor (as is the case above) when working with dynamic code and HTML. The WYSIWYG editor attempts to correct what it sees as mistakes in HTML and will thus produce unintended results if it encounters dynamic code embedded in HTML. To turn off the WYSIWYG editor, click WYSIWYG Editor Off next to the Subject Line text box.
  2. Call addDeliveries. When you call addDeliveries, the array of fields you specify in the function will look for the special loop API message tags and replace them with the content you specify in the messageFieldObject. Essentially, the loop tags will loop through each messagefieldObject specified in the function call. For each messagefieldObject encountered in the loop, the content added for the messagefieldObject will be added to the message, starting with the first array item, and continuing until the last item in the array is encountered. If no content value is added for a messagefieldObject, then that particular messageFieldObject will be skipped over in the loop. Below you can find a modified version of the code example found on the addDeliveries page of the API site. This code sends a message containing the example loop tags above, and replaces them with some generic content.
    
    
    <?php
    /**
     * This example will create a delivery to send a message to a single
     * contact. This example also contains code to add content via loop
     * tags to the message and assumes the message already has the
     * appropriate loop tags added.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');
    
    	$recipientObject = 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($recipientObject);
    	/**
    	* Notice below that when you reference the name of the loop tag via
    	* the API, be sure to leave off 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_0', 'type' => 'html', 'content' => 'A Cool Shirt');
    	$delivery['fields'][] = array('name' => 'productname_1', 'type' => 'html', 'content' => 'Some Nice Shoes');
    	$delivery['fields'][] = array('name' => 'productname_2', 'type' => 'html', 'content' => 'A Trendy Hat');
    	$delivery['fields'][] = array('name' => 'productprice_0', 'type' => 'html', 'content' => '$20.99');
    	$delivery['fields'][] = array('name' => 'productprice_1', 'type' => 'html', 'content' => '$50.99');
    	$delivery['fields'][] = array('name' => 'productprice_2', '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);
    }
    ?>
    
    					
  3. In order to see if your loop tags are functioning as expected, we suggest scheduling some test deliveries and viewing the results. loop tags get processed at send time, so you won't be able to view the end result of adding in these tags in email message previews or a dynamic preview. Below is an example of what the email message above will look like after it has been sent and the content called via the loop tag has been added: Loop Tag Content Added To A       Message
Note: loop tags will not affect the functionality of regular API message tags. Regular API message tags will continue to function as expected.
Warning:
loop tags placed within a URL are not supported. For example, the link below will not work:

					
					<a href="www.google.com/{dynamic_code}{loop}item:%%#item_#%%description:%%#description_#%%{/loop}{/dynamic_code}"></a>;