There are a few things you’ll need to do to ensure that your contacts are required to confirm their subscription before being sent any more marketing messages.

Check out the addContacts function if you haven’t used our API to add contacts. You will need to add your contacts with a status of unconfirmed. Doing this ensures that only messages that contain the %%!confirm_url%% link can be sent to them. This link allows your contacts to confirm their subscription, i.e. their status will become active and they can be sent any message. So go ahead and make sure that you have a created a confirmation message. The confirm_url is available in the Special Tags dropdown in the WYSIWYG editor or you can add it directly to your html.

Now you can schedule this message to be delivered to an unconfirmed contact using the addDeliveries function. The only difference between this and a normal delivery is that you need to specifically mark it as an optin message by setting the optin parameter to True.

And there you have it! A way to automate your double opt-in process through the API so you can be sure that your active contacts truly want to hear from you.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. How To Send A Subscription Confirmation Message At Bronto, we’re very serious about permission based marketing. We...
2. Webforms and Subscriber Confirmation Back in February, Lucas Weber gave us a great post...
3. A Look At Contact Status Within Bronto, your contacts can be labeled with a number...

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

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

Direct Import allows you to post (or send) a file over http without having to interact manually with the contact import forms in the Bronto web application. Why is this so great? Well, without having to do any API programming or much of any setup at all, you can create a system that automatically sends a file with your contacts’ email addresses and any additional information you have, to Bronto.

Using a scheduling utility, such as cron on unix based systems, and an http posting library, such as curl, you can setup a scheduled process to keep your contact data fresh. These are tools that are familiar to most system administrators, so you should be up and running relatively quickly.

Do you have the ability to automatically create exports of your contact data from your local database, but have been logging into Bronto to keep your contact data up to date? Let Direct Import take care of that for you. You’ll always have the most up to date information about your contacts and you’ll only have to set it up once.

So, head on over to the help topics in the application for all of the information and setup options that you’ll need. Less manual work, and fresher data. We hope you’ll like it.

Alex Durzy
Support Engineer at Bronto

Related posts:

1. It’s Coming! The Bronto Spring 2010 Release It’s been a cold and snowy winter and all of...
2. Get Ready: The Bronto Fall 2009 Release You may have noticed Halloween displays at the local...
3. Abandonment Issues? Use Direct Update to Get Over Them! In my last post, DIY Integrations II: Direct Update, I...

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

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