What This Code Does

The example code will read the details of any delivery made in your Bronto account in the last 7 days. It will also print out what message was sent, how many contacts it was sent, how many messages were actually delivered, and how many conversions each delivery received.

With a simple call using readDeliveries, we were able to find out some pretty valuable information. You can use this example to get started making calls of your own and adjust the parameters to get back the data you need. 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. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
2. Using Loop Tags With The API A very useful, but little known feature in Bronto is...
3. Who Loves You: Getting Open Rates Via The API This post only applies to Legacy Version 3 of...

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...

Creating a token

Related posts:

1. Create a Header Without Logging into Bronto Did you know you can now create headers and footers...
2. Using readDeliveries In API Version 4 In version 4 of the API, we have updated the...
3. Personalize Your Contacts, Storing Field Data With The API OK, so your integration is running. You’re adding contacts at...

This post only applies to Legacy Version 3 of the API

You may be using the Bronto API to find out who is reading your deliveries or to send a message, but how about using it to add new contacts to your Bronto list? Using the API, you can add new contacts that you have in a system outside of Bronto. The Bronto API allows you to create up to 1000 contacts in a single request. After the request has been successfully processed, these contacts will be available in the Bronto application and the API.

Adding New Contacts

You create these new contacts using the writeContacts function. This function allows you to give as much or as little information about the new contacts as you have. The only information required to create new contacts using writeContacts is their email address, their status (active, unsubscribed, bounced, unconfirmed), and whether each contact should receive html or plain text messages. Naturally, you can also include other information such as source, any lists the new contacts should be on, and any member field data you have about the new contacts. Since the email address is a unique identifier in the Bronto system, you will not create a duplicate contact should you try to create an email address that already exists. You can, however, update current contacts based on the email address if you choose.

Advanced Features

What if you don’t know if the contacts you are trying to add are all new? What if you don’t want to overwrite contact information already in Bronto? As part of your request, you can specify the mode that writeContacts should use. This tells the API how to handle this request. You can use insert, update or insertUpdate. If you specify insert, the contacts will only be created. If they already exist in Bronto, their information will not be updated or overwritten. The update mode will update information of current contacts. The last mode, insertUpdate will allow you to create new contacts or update contacts if they already exist.

The listsMode attribute of the writeContacts function gives you the ability  to add or remove the contacts from lists. The options for listsMode are replace, insertUpdate and remove. The replace mode removes the contacts from the lists they are currently on and adds them to the lists specified in the request. The insertUpdate mode keeps the contacts on any lists they may currently be on and adds them to the specified lists. The remove mode removes the contact from the lists in the request. You should always have a contact assigned to at least one list since you can only send to contacts on a list.

The fieldsMode allows you to specify how any member field data you send is treated. There are only two modes, replace and insertUpdate. The replace mode will delete any current field data the contact has, and add the field data sent in the request. The insertUpdate mode will only add data to a field if new field data is included in the request. It will leave any fields not specified in the request as they are.

Last but not least is the ignoreStatusChangeIfUpdate attribute. This parameter is really a safety net that keeps you from unintentionally changing the status of a contact. For instance, if a contact already exists in Bronto, but is bounced, this will keep you from accidentally updating them to subscribed and then attempting to send them a message. If you include this parameter with a value of 1 in your request, then a contact who is currently on your list will not have their status changed, regardless of what value you specify in the request.

Some Example Code (PHP)

Below is some example code you can use to get an idea of how the writeContacts function can be used.

Add Away

Now that you have read about the power of writeContacts, we hope you will continue to leverage the power of the Bronto API and discovery new ways to use it.

Andrew Kanes
Support Engineer at Bronto

Related posts:

1. Importing Contacts: Updating Existing Contacts And Adding New Contacts Often times, when managing your Bronto contacts, you’ll want to...
2. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
3. Adding Contacts To A Specific List With Direct Add A few months ago, Lucas Weber wrote a post called...

Would you tow a trailer with a sports car? Would you tighten a bolt with a hammer? Would you eat soup with a knife?

Many of our clients, either by design or due to allocation of resources, have a separation of responsibilities in regards to their email marketing activities. This is especially true when an API integration is involved and the developers handling the integration may or may not also be involved on the marketing side.

The Bronto API is a powerful tool that allows you to control your entire work-flow, from contact management, to message creation, to message sending.  From a development standpoint, this is great in that you have all the power in your own hands. While this may suit your needs perfectly, you may also want to ask yourself what parts of your work-flow are best served by your custom integration, and what would make more sense to save for human intervention in the Bronto application.  Developers and marketers sometimes view things very differently, so let’s look into a couple of places where you can make some choices to affect how you ultimately end up sending messages.

No Code Changes Required

So your developers have integrated your contact database with Bronto. Messages are being triggered off of various activities on your website. Marketing messages are being sent regularly to the various lists managed by your integration. Transactional messages are being sent with a fury from all the purchasing that is occurring on your site. Unfortunately, the messages look like an old paper plate that someone wrote on. If your developers don’t also double as email marketers and graphic designers, then perhaps you want to pass control of that portion of the process. We talked about how message creation, data population, and sending can be separate activities in Give Them What They Want. Your designers can create a visually appealing emails and your developer’s custom integration can continue to trigger the sending of messages and managing contacts.  You shouldn’t have to make any code changes because you want to update the look of a message.

Sending through an API Triggered Automated Message Rule, as we talked about in Owning Automated Messages is another way to not only get great reporting for your triggered deliveries, but to allow more choice for your marketing team. You can turn an AMR on and off, schedule it to expire, control lists of ineligible and eligible contacts, override frequency caps, and control throttling, all without having to make a single code change. Often this type of control is tied into the code that was written by your developers, but Bronto also allows you to make these changes directly from our web application.

Allowing your developers and marketers to do what they do best is one way to get maximum performance from everyone and hopefully yield a successful marketing campaign. Don’t eat soup with a knife.  It burns and you’ll probably end up buying a new shirt.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. I Have the Power: Agency Level API Access This post only applies to Legacy Version 3 of...
2. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
3. Have Logs Will Travel This post only applies to Legacy Version 3 of the...

This post only applies to Legacy Version 3 of the API

Since conversions are in many cases the purpose for sending an email, they have been covered in great depth in previous posts. You may to start with the basics of conversion tracking and how to set it up by John Gunther. Also, as Adam Covati recently wrote, a conversion doesn’t necessarily just mean a purchase.
Don’t get me wrong, the Bronto reporting tools are great! That said, rather than cover the what and how behind setting up conversion tracking and the reports in the Bronto application, let’s look into how we can use the API to create a custom reporting app or mash-up that gives you exactly what you want, how you want it, when you want it.

Whiz-Bang

So we don’t know how to get the conversion data yet. First, let’s determine what we’re going to get, in order to see what we could possibly build with it. Ultimately, at the individual contact or delivery level, we’ll be able to retrieve the IP, URL, type, description, revenue, and time created for a conversion. You can group by URL or revenue amount, or add an IP locator to track from where in the world you get the most conversions. Hopefully there will be lots and lots of data, because that means your contacts are clicking through and converting.

Tools Of The Trade

If you’re already using the API to do some contact management or some other custom reporting, then you have most likely already used the functions related to contacts and deliveries, namely readContacts and readDeliveries. In order to get to the conversion data, we’ll need to reference either a contact or a delivery by ID. Both of these functions return the IDs for their respective objects. Note: all of the object IDs remain static, so if you have a particular contact or delivery you are watching, there is no need to re-read the object to retrieve the ID.

The only other functions we’ll need are readStreams and readStreamViews. For each object in which you are interested(a contact or a delivery) you need to first call the readStreams function to retrieve the click stream instances. Then for each of these, you will need to call the readStreamViews function with that particular stream ID. Something to consider – each time you call the readStreams function for a deliveryId you will get all of the click streams, not just the new ones since the last time you called the function.

If You Write It They Will Come

Small automatically run applications or scripts are great at getting data and transforming it into a customized format, so you don’t have to do any of the work manually. As we have seen, the API has the necessary functions to get at all of that great conversion data that you see in the Bronto application. Why not take advantage of it and create your own report-wizard-gizmo-script-gadget-formatter-application?  Let us know how you’re using the data(and what you named it!)

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Who Loves You: Getting Open Rates Via The API This post only applies to Legacy Version 3 of...
2. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
3. Have Logs Will Travel This post only applies to Legacy Version 3 of the...

This post only applies to Legacy Version 3 of the API

If you have been sending personalized messages to your contacts, then you already understand how useful this marketing technique can be. If you would like to start exploring how to use personal information you have about your contacts, take a look at this post by Frank Chapman on Getting Personal With Your Contacts.  But what about those of you that are sending messages with data that isn’t available until you send the message? API message tags to the rescue! You can think of API message tags as place holders that you can fill in with data when you send a message through the API. Adam Covati touched on API message tags in Owning Automated Messages. API message tags are clearly useful in the case of a receipt or some other transactional type of message like the following example. You will notice that the message tags can exist within the context of an HTML tag, as is the case with the address fields in the table. The %%#items%% tag could be passed in as a table, or could be a simple list of items. Since API message tags are just empty place holders, they can be used for anything that you want to contain up to date/personalized information, or data you don’t have at the time the message is designed.

Setup

So let’s make sure you know how to pass this data in from the development side. If you take a look at the documentation for the writeDeliveries function, you will notice the optional fields parameter. This is an array of messageField objects which contain the name of the field, the type, and the actual content. The type is the type of message for which the data is destined, not the type of the data. In some cases, the difference between the data you send into an HTML message and the data you send into the text version of the message will be different. A transactional purchase receipt, for instance, would likely contain a list of items purchased. The HTML version of the message might get an HTML table structure, while the text version of the message would get a simple comma separated list of items.

Passing In HTML

Wait a minute, HTML? That’s right! You can pass in more than just a simple name of an item, or a purchase price. You can even make styling or formatting decisions at send time. You would probably want to leave most of the styling to your email designers, but clearly there is the opportunity to do a lot of interesting things with API message tags.

Hopefully you can now see how useful API message tags are. If you have been using the API and wondered what these optional tags were, run to your nearest code editor or IDE and send some messages with personalized information courtesy of API message tags.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Feed Me, Seymour! Using RSS Feeds Can Give Your Message New Reach In the past few years, web technology has provided us...
2. Keep Your Eye On The Sparrow: Using The API To Retrieve Conversions This post only applies to Legacy Version 3 of...
3. Using Loop Tags With The API A very useful, but little known feature in Bronto is...

This post only applies to Legacy Version 3 of the API

So far, most of the API examples and blog posts that we’ve written have dealt with a single account. But what if you have an agency account and want to automate tasks or have other needs that require the use of the API? The chances are pretty good that you will want to perform these tasks for more than one, or even all of your subaccounts. With agency level API permissions, an agency user has the ability to login to the API and perform tasks in any subaccount just as though it was logged into the subaccount itself.

Let’s Get Started

First, make sure you have an agency user with agency API access turned on.

Note that this user does not need to have administrator privileges. This allows you to restrict the amount of access this user has in the Bronto web application, while still allowing access to the API.

Now you can login to the API using this username, password, and the sitename from from the Sign In tab of your agency preferences. As with logging into the agency portion of the Bronto web application, you can’t perform subaccount activities just yet (i.e. updating contacts, sending messages, etc).  You’ll first need to login to a specific subaccount by using the optional siteId parameter in the login function. This siteId can be retrieved by using the readAccounts function. In fact, this is the only function you’ll have access to as an agency API user.  Once you have these siteIds, you may choose to store them locally. This way you won’t have to go through the first step of logging in as the agency user and reading them.

Keep This In Mind…

If your subaccounts change somewhat frequently and you are creating an interface to allow someone in your organization to perform various subaccount activities, you may want to continue to perform the initial agency login and retrieval of siteIds step. Doing this allows you to present an up to date list of all your subaccounts.

Included is a PHP example that shows how you can use a single login function for both agency and subaccount logins. Let us know if you have any questions in the comments section below.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Have Logs Will Travel This post only applies to Legacy Version 3 of the...
2. Who Loves You: Getting Open Rates Via The API This post only applies to Legacy Version 3 of...
3. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...

This post will assume that you have an understanding of how Direct Update works and how to implement it on your site. If you have questions on the basics or usage of Direct Update, please check out the help topic called Enabling Direct Update in the Bronto application.

Getting this set up is as simple as setting up a couple of fields, creating two separate Direct Update strings, and placing them in the right location on your site. Let’s get started…

The Fields

First, the easy part, creating two fields. We’ll use these fields to monitor when a contact has placed something in their cart, and when they complete a purchase.  We’ll call our first field ItemInCart. This can be pretty much any type of field you’d like. For simplicity’s sake, we’ll leave it as a text field.  The next field we’ll call CompletedPurchase. Again, this can be any type of field. I would recommend a date type field so that you can use this field data in multiple ways to target contacts.

The First Direct Update Statement

Next, we’ll need to set up the first of our two Direct Update code snippets.  The base code can be found by going to Home->Settings->Analytics, and then scrolling down to the Direct Update section.  In addition to grabbing the code, make sure that the check box under Direct Update is checked. Doing so will activate the feature.

Let’s take a look at a sample of the base code first.

<img src="http://app.bronto.com/public/?q=direct_update&fn=Public_DirectUpdateForm&id=cdagfvzjskjuipnbbdjdvbiwgfkdbbb" border="0" alt="" width="0" height="0" />

The goal of the first snippet is to let us know that someone has placed an item in their shopping cart. We’ll need to add an operator to the end of the snippet that sets the ItemInCart field to a positive value. To do this, we’ll use the following code:

field1=ItemInCart,set,Yes

The completed Direct Update code snippet would look like this:

<img src="http://app.bronto.com/public/?q=direct_update&fn=Public_DirectUpdateForm&id=cdagfvzjskjuipnbbdjdvbiwgfkdbbb&field1=ItemInCart,set,Yes" border="0" alt="" width="0" height="0" />

Once you’ve got this first snippet, it will need to be placed on your website. Preferably, you should place it on a confirmation page that comes up after a contact adds an item or items to their shopping cart. That way, when they reach this page, the Direct Update code snippet will activate and update their ItemInCart field to ‘Yes’.

The Second Direct Update Statement

Now we’re ready to set up the second and final piece of Direct Update code. We’ll start with the base code again and build from there. This time around, we need to add an operator that sets a contact’s CompletedPurchase field to a certain value. I recommend using the current date. This will allow you to use this data for other segmenting purposes.

field1=CompletedPurchase,set,10/27/2009

In order to set to the current date, you will need to use some simple javascript that will be run from your own server. Click here and check out Example 1 for a simple script to call the current date. It is important to note that the date must be specified in the format you have designated for date fields on the Formatting page located at Home->Settings->Formatting. In addition, we need to remove the positive value from the ItemInCart field so that we don’t accidentally pull in people that have completed a purchase.  We’ll use the following to do so:

field2=ItemInCart,set,No

The completed Direct Update code snippet would look like this:

<img src="http://app.bronto.com/public/?q=direct_update&fn=Public_DirectUpdateForm&id=cdagfvzjskjuipnbbdjdvbiwgfkdbbb&field1=CompletedPurchase,set,10/27/2009&field2=ItemInCart,set,No" border="0" alt="" width="0" height="0" />

This second code snippet will also need to be placed on your website. This one should be placed on the order confirmation screen, after the purchase has been completed. It will set the contact’s CompletedPurchase field to the date defined, and will set their ItemInCart field to No.

Segmenting with Reckless Abandon

All that remains is to find the people in your contact list that have abandoned their shopping cart and give them a little incentive to complete the purchase! This can be very easily done by creating a simple segment that searches for contacts in your account that have a value of Yes in the ItemInCart field. Once that segment is created, all you have to do is send your message to it.

Careful Considerations

One small caveat to this post is that the whole thing will only work if a couple of conditions are met. First, the contact must have clicked on a link in an email sent via Bronto, which will open a tracking cookie on their computer. The cookie will allow the Direct Update code to work. Second, they must have cookies enabled in their web browser.

There you have it, a relatively simple way to set up an abandoned shopping cart tracking mechanism for your Bronto contacts. Keeping track of when your contacts do not complete a purchase can be just as important as keeping track of when they do. Are you currently using this method to increase conversions? Are you using a different method? Let us know in the comments.

Lucas Weber
Bronto Client Services

Related posts:

1. DIY Integrations II: Updating Contact Field Information With Direct Update Integrating your website or database with a third party...
2. DIY Integrations: Getting Contacts Into Your Account With Direct Add Integrating your website or database with a third party application...
3. Direct Unsubscribe Grows Up In the beginning, our Direct Unsubscribe feature was tucked away...

Using a web service is a little bit like a leap of faith.  You no longer have total control of the code and are depending on the service to perform a chunk of your work flow.  The benefits are obvious, in that you don’t have to develop or maintain that code.  The downside is that when something does go wrong, it’s tempting to blame the web service provider. However, this is not always the case and in the event that something does go wrong, you need a way to determine where the failure was. One way is to use a SOAP testing tool as we’ve seen in Washing with SOAP part 1, 2, 3.  This is a quick way to verify that the web service is doing what it’s supposed to.  But if you need to debug your code, then you will need a way to output the SOAP requests and responses that you are sending and receiving.  This will also be valuable information to show to the provider of the web service you are consuming. So, let’s look at how to do this in a few different languages.

PHP Logging Example

PHP(version 5+) gives you easy access to the last request and response through the SOAP Client object.  The functions __getLastRequest() and __getLastResponse() will return a string representation of the last request and response.  You can either echo this string to standard output, as with the very simple file logger class in this example, or more than likely in your production code you will be logging it to a file.  Get the code

Python Logging Example

If you’re using the Suds SOAP library for Python, you can enable logging through Python’s own logging library.  You won’t need to directly access the request and response strings. You can also control how much information you receive by setting the logging level. Additionally, the library allows adding a file handler to pipe the output to a log file.  Pretty convenient, right?  Get the code

Java Logging Example

With Java, using the JAX-WS SOAP stack, things get slightly more complicated.  If you worked through accessing the SOAP header through the use of a SOAP message handler, then you’ll be familiar with the process here.  What we’ll be doing is writing a handler whose purpose is to intercept requests and responses, log them, and then pass them along to the next handler. Here you will find the handler code, as well as the code to associate it to the binding.  Again, this is for use with Java’s JAX-WS library.  If you’re using Apache Axis or some other SOAP library, you will likely have alternate methods to log SOAP messages.  Get the code

While some languages are easier than others in terms of logging SOAP messages, you should always write your code with the idea that at some point, something may go wrong. When something does go wrong, you’ll need a way to investigate what happened.  Without being able to see the SOAP messages that your application and the Bronto API are passing back and forth, you will have a much harder time debugging your code.  So with these examples in hand, go forth and log those SOAP messages.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Who Loves You: Getting Open Rates Via The API This post only applies to Legacy Version 3 of...
2. I Have the Power: Agency Level API Access This post only applies to Legacy Version 3 of...
3. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...