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

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

Did you know we had a function in our API to clear all contacts from a list? It was recently added and is conveniently called clearLists. This function will remove the contacts from a list, but it will not remove the contacts themselves from Bronto.

Here are a couple sample PHP functions that make use of the readLists and clearLists functions.  With these functions you can clear one or more lists of all contacts, without having to individually remove contacts from the lists.

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. Clear that List using the API v4 Last fall, Alex explained how to Clear Contacts From...
3. Welcome Friend! Adding New Contacts Using the API This post only applies to Legacy Version 3 of...

This post only applies to Legacy Version 3 of the API

You know you can update contacts and schedule deliveries through the Bronto API, but what about access to all that great statistical data such as opens and clicks for your contacts and deliveries?  Let’s look at the readOpens function and how we might use it to determine who loves you, or at least who loves to open your messages, the most.

Open Sesame

The readOpens function allows us to gather opens at a very granular level, either by contact or delivery id. Using the results you get back from this function, you can generate a list of the contacts that opened the most emails. You will need to be aware of the difference between total opens and unique opens. If you’ve used the Bronto web application and looked at any of the message reports, you’re most likely already familiar with this concept. A contact can open an email multiple times, and depending on your particular use case, you may or may not be interested in this. For the purposes of this exercise, we’ll be looking at unique opens. With a unique open, it doesn’t matter to us here if a contact opened a single email 20 times, we only want to count the open once.

First, let’s outline what we need to do in order to accomplish our task, and then we’ll look at an example in PHP.

1. Login to the API.
2. Retrieve a list of deliveries for a date range.
3. Retrieve the opens for each delivery.
4. Get the contacts that opened the delivery.
5. Aggregate the total number of emails opened by each contact.

Feel free to download this script, shown below, and begin tweaking it for your own requirements.

Getting Opens in PHP

Now What?

We now have a list of contact ids along with the number of emails each contact opened. You can use these ids for other operations, such as managing the lists to which the contact is subscribed, or sending the contact a message. Perhaps you want to base a future email on the number of times a contact has opened previous emails. If you actually dig a little deeper into the data that is returned by the readOpens function, you will also see that you can get the IP address from which the open originated. Maybe you want to get a sense for where your emails are being opened most often? You can use this data along with an ip address lookup service to generate this.

The other way to retrieve open information is by contact id.  If you have a specific contact or list of contacts in which you are interested, you may decide to use this method instead.  Again, you will need to be aware of unique verses total opens, but the process will be fairly similar.  What other information is available you ask?  Next time we’ll look at link/click data so you can see who loves you enough to click a link.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Spring Cleaning: Clearing Contacts From Lists This post only applies to Legacy Version 3 of the...
2. Using readDeliveries In API Version 4 In version 4 of the API, we have updated the...
3. Keep Your Eye On The Sparrow: Using The API To Retrieve Conversions This post only applies to Legacy Version 3 of...

This post only applies to Legacy Version 3 of the API

In the first two parts of this series, Washing With SOAP: Part 1 and Washing With SOAP: Part 2, we saw how a SOAP testing tool, such as soapUI, can be used to test and learn about a particular web service; In this case, the Bronto API.  We logged in to the API, created some contacts, and retrieved some contacts.  These operations are useful for keeping a contact database in sync with Bronto.  In this post, we’ll look at how to actually schedule a delivery.

Create a List

You can send to a list, contact, segment, or combinations of all three.  In this case, we’ll actually be sending to a list that has been created in the Bronto application.  You can manage your lists and segments in the application and send to them from the API, but you’ll need to obtain the id of the list or segment first.

Login and Retrieve the List and Messages IDs

Refer to Part 2 if you need to review how to login and obtain a session ID. I previously created a list in Bronto called “mynewsletter”, and as you can see in the request, I specified this in the filter criteria. You can also retrieve all of the lists by not specifying any filter criteria, but we know the name of the list, so let’s use it. We also need to know the id of the message we want to send, so we need to use the appropriate read operation and filter. Here I have retrieved a message called “julynewsletter”.

Request – readLists

Response – readLists

Request – readMessages

Response – readMessages

Schedule The Delivery

You can schedule a delivery to be sent immediately, by specifying “now” as the send time, or you can alternately specify a UTC date and time. Try scheduling the delivery for far enough in the future so that you have time to log into the application and see it in your outbox.  Let’s schedule something for tomorrow morning at 9:00 AM EDT(13:00 UTC).

Request – writeDeliveries

Response – writeDeliveries

If you log into the application, you will see this delivery just as if it had been scheduled in the application. Now that you’ve seen how to use some of the most commonly used operations, and have an easy way to access and try out API operations without writing code, go explore some of the other operations. For instance, you may want to collect open and click data about your contacts and deliveries that can be used in a custom data analysis report. In an upcoming post we’ll look at some code that uses the readOpens and readClicks functions.

For informationon on the Bronto API visit http://api.bronto.com/, or feel free to leave us a comment in the comments section below.

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. May I Have Another User As part of version 4 of the Bronto API, we...
3. Using the New readContacts Function Over the past few weeks, we have looked at how...

Last time we discussed how to setup Bronto API access and the benefits of using a SOAP testing tool.  This time we’ll look at some of the actual requests and responses so you can see what the API can do.

If you already have soapUI installed, go ahead and create a new Project and point it at the Bronto WSDL.

Expand the project to expose all of the available operations. Each operation should already have a single request created for you. The nice thing about a tool like soapUI is that you can invoke the functions and see the XML requests and responses all in the same window.

Login

Double click on the login request to see what the parameters for the operation are and edit the request appropriately with your Bronto credentials.  You will find your sitename in Bronto under Home->Settings->General.  Your login request message should look something like this:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.bronto.com">
<soapenv:Header/>
<soapenv:Body>
<api:login>
<api:username>your_bronto_userid</api:username>
<api:password>your_password</api:password>
<api:sitename>your_sitename</api:sitename>
<!--Optional:-->
<api:siteId></api:siteId>
</api:login>
</soapenv:Body>
</soapenv:Envelope>

Note that the tool shows all of the parameters, including the optional ones. You can go ahead and remove those if you want to clean up your XML. Now invoke the operation with the green arrow.  If your account is setup correctly, you should get back a response that looks something like the following:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://api.bronto.com">
<SOAP-ENV:Body>
<ns1:loginResponse>
<ns1:return>
<ns1:success>true</ns1:success>
<ns1:sessionId>aaaabbbbccccddddeeeeffffgggghhhh</ns1:sessionId>
<ns1:serviceURL>https://api.bm23.com/api/?q=mail_3</ns1:serviceURL>
</ns1:return>
</ns1:loginResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If the login was successful, you will see a value of “true” in the success field.  Also, you will want to keep the sessionId that you got back handy – you’ll need it in all subsequent calls to the web service.

Create Some Contacts

Now let’s create some contacts. We’ll create two at the same time here. The current Bronto API allows up to 1000 in a single request.

Request


<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:api="http://api.bronto.com">
<soapenv:Header>
<api:sessionHeader>
<api:sessionId>aaaabbbbccccddddeeeeffffgggghhhh</api:sessionId>
</api:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<api:writeContacts>
<!--1 or more repetitions:-->
<api:contacts>
<api:email>first@email.address</api:email>
<api:status>active</api:status>
<api:msgPref>html</api:msgPref>
</api:contacts>
<api:contacts>
<api:email>second@email.address</api:email>
<api:status>active</api:status>
<api:msgPref>html</api:msgPref>
</api:contacts>
<api:handler>
<api:mode>insertUpdate</api:mode>
</api:handler>
</api:writeContacts>
</soapenv:Body>
</soapenv:Envelope>


Response

Assuming the request is successful, you should see these contacts in the Bronto application.  Of course, there is also a read function that will allow you to retrieve all or some subset of your contacts.

Read Some Contacts

Let’s read all of the active contacts that were created today(edit the date as appropriate). If you’re following along, you should get back the two contacts you just created. If you remove the optional criteria block, you will be returned all of the available contacts (Note: if you have more than 1000 contacts you will be returned groups of 1000, and will need to use the readNext function to get any additional groups).

Request

Response

You will find that many of the read and write functions operate similarly to the examples above, so feel free to go ahead and give them a try.  We’ve already seen an example of an API Triggered Automated Message Rule in Owning Automated Messages.  Next time we’ll look at how to schedule a delivery using one of these rules, the API, and our handy SOAP testing tool.

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. May I Have Another User As part of version 4 of the Bronto API, we...

If you have ever integrated your organization’s application(s) or database(s) with an external data source, chances are you used a web service, or even multiple web services.  These generally come in two flavors: SOAP (Simple Object Access Protocol) and REST (Representational State Transfer). Search around on the Internet and you’ll find plenty of advocates for one or the other.  When you get right down to it though, both are equally adept at getting a job done, i.e. getting your system to talk to another system. In the case of Bronto, we provide an API in the form of a SOAP web service.  Visit our API documentation for more detailed information.

First Things First: Setting Up API Permissions In Bronto

To make use of the Bronto service, you will need to create a Bronto user in your account with API access. To enable API access for a user, go to Home->Users and click on a user or the edit pencil icon to the right of the user. Once you are on the Edit Permissions page, make sure that API Permissions are enabled on the Other tab.

Getting Familiar With SOAP

SOAP services use XML as their language, and HTTP for the transmission of the messages.  They also “advertise” what operations are available in a file called a WSDL (Web Services Definition Language).  If this sounds complex and painfully hard to program, fear not, because the essence of how to use a SOAP based web service is this: send it a message that tells it to do something, and wait for the response.  When you get around to integrating with your system, you will generally do this in the programming language of your choice (most of the popular languages provide methods to call SOAP services).  If not, you can always resort to constructing the XML messages and sending them over HTTP, just like any other request for a web based resource.  But what do these XML messages look like, and how would one use a SOAP service without knowing a bunch of programmer mumbo jumbo?

Getting A SOAP Testing Tool

Simple actually.  Use a SOAP testing tool that’s independent of your programming language.  Web service documentation is great, but you really care about what that service does with your data, so why not jump in and start using the service right away.  A good testing tool is great for learning the ins and outs of a web service before you even start writing code.  It will also be your best friend when something goes wrong and you’re not sure if the problem is in your code, or is just the way the web service functions. Most testing tools, such as soapUI, which is freely available for download, allow you to generate the XML messages for a web service by parsing its WSDL. With soapUI, all you will need to do is create a new project and point it at the Bronto WSDL. A tool like soapUI allows you to utilize and test out a web service without worrying about any coding details.  This is useful before, during, and after the development process. Once you have explored the operations that the web service provides and feel comfortable with how they work, you can do some coding yourself or try out some of our sample code on http://api.bronto.com.

Sound good so far? Interested in learning more? Stay tuned for part 2 of this blog post series on SOAP. Next time we’ll look at what the SOAP requests and responses look like for some of the more commonly used operations. Until then, go ahead and explore the API yourself, no programming required.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. Have Logs Will Travel This post only applies to Legacy Version 3 of the...