Welcome Friend! Adding New Contacts Using the API

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