Last fall, Alex explained how to Clear Contacts From Lists in v3 of the API. You now have the same ability in v4 API using the clearLists function. All you need to do is specify the list id returned from the addLists or readLists function. After you call clearLists, all your contacts will be removed from the list, however, they will remain in Bronto.

Here is a sample SOAP message that would clear two lists.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v4="http://api.bronto.com/v4">
   <soapenv:Header>
      <v4:sessionHeader>
         <sessionId>b058d5e0-7cb4-4578-b16f-a4c049079207</sessionId>
      </v4:sessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <v4:clearLists>
         <list>
            <id>0bbb03ec0000000000000000000000038e93</id>
         </list>
         <list>
            <id>0bbb03ec00000000000000000000000390d0</id>
        </list>
      </v4:clearLists>
   </soapenv:Body>
</soapenv:Envelope>

This PHP script would create a SOAP message like this.

<?php
/**
 * This example will clear two lists of all contacts on those lists.
 * You must edit the code to refer to the list id you wish to clear.
 */

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

try {
        $token = "#####API TOKEN###########";

        print "logging in<br>";
        $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));

        $ids = array(array('id' => '0bbb03ec0000000000000000000000038e93'),
                   array('id' => '0bbb03ec00000000000000000000000390d0'));

        $res = $client->clearLists($ids)->return;

        if ($res->errors) {
                print "There was a problem clearing your lists:<br>";
                print $res->results[$res->errors[0]]->errorString . "<br>";
        } else {
                print "Lists have been cleared<br>";
        }
} catch (Exception $e) {
        print "uncaught exception\n";
        print_r($e);
}
?>

Now you are able to quickly and easily clear your lists without having to find everyone on the list. We do suggest you exercise caution when using this function, as there is no rewind button. I hope you find this new functionality useful. Let us know if you have any questions.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
2. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...
3. May I Have Another User As part of version 4 of the Bronto API, we...

Using Loop Tags

To make use of loop tags:

1. Add {loop}{/loop} tags to the dynamic code in a 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}

   Click the image below to enlarge

   

   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 we recommend turning 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. Depending on which version of the API you are using, call either addDeliveries (Version 4) or writeDeliveries (Legacy Version 3). When you call writeDeliveries or 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 for each 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 each 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.

   NOTE: The code example below applies only to version 4 of the API, but you can use it as reference for using loop tags with the writeDeliveries function in legacy version 3 of the API.

   To easily copy the code below, move your mouse over the top right corner of the code example. Four buttons will appear. Click View Source or Copy To Clipboard to copy the code below in plain text format without line numbers.

   /**
    * 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
           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);
   }

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 a message previews or a dynamic preview. Below is an example of what the message above will look like after it has been sent and the content called via the loop tag has been added:

   Click on the image below to enlarge

   

Conclusion

That was a lot of information to cover, and working with loop is probably not something you should try and tackle unless you are comfortable using the API. However, with the right know how, incorporating loop tags into your email marketing program should be a straight forward process that can allow you to do some pretty powerful things. 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

Related posts:

1. Give Them What They Want With API Message Tags This post only applies to Legacy Version 3 of...
2. Using readDeliveries In API Version 4 In version 4 of the API, we have updated the...
3. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...

As with our other API functions, there is not only the ability to add, but also to read, update and delete API Tokens. These functions give API users the ability to manipulate their API Tokens just as a user logged into the web application is able to.

Let’s Jump In

First let’s take a look at an example of a SOAP message to create a token:

The response message that is returned by the API will contain the Id of the newly created token and will look like this:

You can then use the Id to reference that token, for instance when using the readApiTokens.

You can also use the filters available for readApiTokens to search for tokens based on their name, or return all the tokens available to a sub-account or an entire agency. Of course, after you create the API Token, you are now able to use it to log into the API. We hope you find this new functionality useful and please let us know if you have any questions.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. May I Have Another User As part of version 4 of the Bronto API, we...
2. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
3. Agencies Can Create New Accounts Using The API Last month we discussed how to create headers and footers...

As is standard, we have included create, read, update, and delete functions for logins. We have also made an effort to make the objects that are accessible through the API very closely mirror their web application counterparts. In other words, creating a contact, message, account, login, etc through the API should feel very similar to creating one in the application.

The quickest way to get a sense for an object and its parameters is to read one or more that have already been created. So check out the readLogins function and give it a try with an empty filter. Here’s an example SOAP request/response generated from soapui:

All of the permissions should look familiar if you have had a chance to edit a user’s permissions in the application. Hence, when you create a login object through the API, you can specify those same permissions. Here is what the SOAP request for the addLogins function looks like.

With these new functions in hand, you will be able to automate the management of your account, whereas previously this was only possible by logging into the Bronto web application.  We hope you find them useful and welcome any feedback.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...
2. Agencies Can Create New Accounts Using The API Last month we discussed how to create headers and footers...
3. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...

What’s New?

First of all, those of you who are currently using the Direct Unsubscribe snippet as it is now will be able to continue to do so without any changes being made. Your contacts will still be able to use your form, enter their email address, click submit, and (once their email address is appended to the Direct Unsubscribe snippet) unsubscribe.

The big change that has been made to Direct Unsubscribe is that it can now use a Bronto tracking cookie to automatically pull in the email address of the contact who clicked on a link in a message you sent from Bronto and unsubscribe that individual. This is great for people who would like to implement a truly one-click unsubscribe process that uses a custom unsubscribe landing page. The other change is that we’ve moved the feature from the unsubscribe page out to the Data Exchange area (Home tab > Settings > Data Exchange).

How To Use It

Using Direct Unsubscribe is actually pretty simple, but like any of our snippet based integrations, it can require some web programming knowledge. To get the snippet just go to the Home tab > Settings > Data Exchange and check the Direct Unsubscribe checkbox.  This will expand the box and reveal the code.  You’ll notice that the code does not include any area for email address. This is because it can now be used without using the Bronto tracking cookie. In other words, you can unsubscribe contacts even if they arrive at your unsubscribe page from a source other than a message you send via Bronto. If you would like to append the email address manually, just add the following to the very end of the snippet:

&email=email@example.com

Of course you will need to replace email@example.com with the email address of the person who wants to unsubscribe. This can be done by pulling the email address that the recipient enters into the form on your end. If you append an email address yourself, it will always take precedence over the the cookie used to identify the email address.

So that is an overview of the new and improved  Direct Unsubscribe feature, if you are currently using this feature or if you have any questions, please let us know!

Lucas Weber
Bronto Client Services

Related posts:

1. Are You Aware of Direct Unsubscribe? Typically contacts in Bronto can unsubscribe by either clicking the...
2. Abandonment Issues? Use Direct Update to Get Over Them! In my last post, DIY Integrations II: Direct Update, I...
3. Adding Contacts To A Specific List With Direct Add A few months ago, Lucas Weber wrote a post called...

You know that this data can be imported using a csv file and the import tool in the Bronto web app, but how about with the API? We talked about adding contacts using version 3 in Welcome Friend! Adding New Contacts Using the API, but let’s look at the contactObject to see how we might use it to add or update contacts with version 4.

Let’s first look at the fields portion (in bold) of the addContacts SOAP request message below(note: updateContacts uses the same contact object and readContacts returns the same object).

You might never need to actually look at a SOAP message or a WSDL if your IDE/SOAP library takes care of that for you, but it can definitely be helpful when trying to understand how the requests and responses are passed back and forth. Most of the attributes are self descriptive and using them is hopefully straight forward. The fields attribute however takes a little more explaining.

In the WSDL you will see that it is defined as:

<xs:element maxOccurs="unbounded" minOccurs="0" name="fields" nillable="true" type="tns:contactField"/>

This tells us that the fields item is a group of zero or more contactField objects. In most programming languages, that type of structure would be represented as an array of contactField objects. These contactField objects in turn contain two items; fieldId and content. The content is the actual data that you want to store and the fieldId is a static id that is assigned to each of your fields when they are created. The fieldId can be retrieved using the readFields function. Since the fieldIds are static, it probably makes sense to go ahead and store these locally so they do not need to be read each time you want to use them. The easiest thing to do is to call readFields once with an empty filter and store the field information in a configuration file. That way, adding or removing fields will not require changes to your code.

With this information in hand, it will hopefully make more sense on how you would go about passing in contact information. So don’t leave those fields empty any more.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. DIY Integrations II: Updating Contact Field Information With Direct Update Integrating your website or database with a third party...
2. Welcome Friend! Adding New Contacts Using the API This post only applies to Legacy Version 3 of...
3. Adding Contacts To A Specific List With Direct Add A few months ago, Lucas Weber wrote a post called...

This new function, and its associated functions deleteHeaderFooters, readHeaderFooters and updateHeaderFooters, allows you to manipulate the name and contents of your headers and footers from outside the Bronto application. The arguments are name, html, text and isHeader. These allow you to specify the name of the header or footer, the html and plain text content of the header or footer, and how it should be used.

Do you design your headers and footers in an external application and then log into Bronto to create your header and paste in your content? Using these four functions, you can create, modify, read, and delete headers and footers from an external, customized application. Now you can avoid the process of cutting and pasting your content into Bronto by sending a SOAP message like this

Here is some sample PHP code to generate this SOAP message:

If you have any questions, feel free to leave them in the comments section below.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Agencies Can Create New Accounts Using The API Last month we discussed how to create headers and footers...
2. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
3. Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...

Using the contactFilter

Lets say you were interested in all active contacts created after June 1, 2009 at 6am ET. You would create a SOAP message like:

Using the readContacts function, you can also filter on criteria such as email address, modified date, which lists or segments the contacts are on, message format preference, source and customSource. You can also specify if the contacts should match all or any of the filter criteria by defining the filter type as an AND or an OR.

Aggregate Information Returned by the readContact Function

The updated readContact function also returns aggregate information for each contact. The results now include numSends, numBounces, numOpens, numClicks, numConversions and conversionAmount. These metrics tell you the total number of deliveries sent to a contact, the number of times deliveries sent to a contact that have bounced, the number of opens recorded for the contact, the number of clicks recorded for the contact, the total number of times a contact has converted, and the total amount of any conversions. This is in addition to all the other information about a contact that is returned.

Let us know if you have any suggestions or questions in the comments section below!

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Filtering Result Sets Did you know that all of the read functions available...
2. Token, Token, Who Wants a Token? Another new feature of version 4 of the Bronto API...
3. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...

If you used the previous version of the API you may have used the filtering that was available. You had the option to check equality(=) for all data types as well as inequalities(>, <, >=, <=) with numeric and date types. In version 4 of the API we have added some very useful filter operators.  Let’s take a closer look at a couple of the new operators.

To The Operators Jeeves

StartsWith / EndsWith can be used as a string comparison and are especially useful when trying to filter down your contacts by matching a portion of their email address. For instance, let’s say you wanted to see how engaged contacts with only yahoo.com have been.  You could use the EndsWith operator and “yahoo.com” as the value to request just these contacts.  Once you have these contacts you can use the aggregated statistics that are returned to create a customized report with just the information that you need.

But Wait, There’s More…

So you actually want all of the contacts except those yahoo.com addresses?  You’re in luck, you can change that EndsWith operator to DoesNotEndWith.    Why stop there?  You can add additional filters to crop that list down even more.  You only want contacts that signed up this year?  Add a filter using the new SameYearAs operator?  Want to get contacts that signed up specifically between two dates?  Check out the Before / After and BeforeOrSameDay / AfterOrSameDay.

With this version of the API we have made an effort to open up the filtering to give you more options. As your contact database grows this will be increasingly important to you. Hopefully you will find these additional possibilities helpful. Let us know what you think!

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Filtering Result Sets Did you know that all of the read functions available...
2. Using the New readContacts Function Over the past few weeks, we have looked at how...
3. May I Have Another User As part of version 4 of the Bronto API, we...

What’s New In Version 4?

Gone is the universal readFilter with its readCriteria attributes. In version 4, each read function has its own filter object with associated named criteria parameters. As with V3, you can still opt to perform the read with an empty filter in order to retrieve all of the available records for that request. In some cases, this may be the desired effect. However, in other cases, filtering the returned results is essential. The objects that you will probably want to filter most are contacts, since this is likely your largest set of objects.

Filtering Contacts

Let’s take a look at the options available in the filter for the readContacts function. On api.bronto.com, you will find the contactFilter object that is one of the parameters of the readContacts (Click here for example code) function. The parameters of the various filter objects correlate to their associated object. All of the parameters you see in the contactFilter object are all in the contact object itself, except for one. That is the type parameter. This parameter takes on the same role as the operator parameter in V3. That is, it allows you to set multiple criteria and join them with an AND or OR operator. We have also added some new operators that allow for more advanced filtering. Take a look at the comparisons that are now available in the filterOperator.

If you want to give it a try without writing any code and don’t yet have a handy SOAP testing tool, see Washing With SOAP. You’ll also want to review Logging into the API v4.0. Once you have done that, you can go ahead and pick out your favorite read function and start trying out some of the different filtering parameters.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Filtering Result Sets, Part 2 Last time we looked at the basics of Filtering Result...
2. Using the New readContacts Function Over the past few weeks, we have looked at how...
3. May I Have Another User As part of version 4 of the Bronto API, we...