Four-Eight-Four [dot org]

I’ve been working with a client that has been using Bronto for email marketing purposes for several months now. Recently, we made the decision to activate Bronto’s SOAP API access for their account so that we can add contacts to our mailing lists automatically. One reason we wanted to do this was because a few months ago, we put in place a privacy policy that specified that we’d use a double opt-in methodology for adding people to our lists, and we found that manually importing the contacts every so often just wasn’t working … only about 1-2% of the people who had checked the first opt-in box were confirming their subscription. I expected that some people might change their mind and not confirm, or the confirmation request might get caught in their spam folder/filter, etc., but 1-2% is pretty low. My guess is people forgot they’d checked the “yes, I want to subscribe to your newsletter” box in the days since they’d done so, or something like that.

Documentation for the Bronto API exists, but is sparse for somebody who is just getting started with it, even if they do have a good bit of experience with SOAP. Once I got past the provided “Hello, World!” tutorial, I found myself in the dark using trial and error to figure out how things worked.

So, I decided to start out by demonstrating how to add (or update) a contact, and add that contact to a mailing list in your Bronto account.

I’m assuming that anybody reading this has already enabled API access (it’s $150 extra a month), created a user with API access in their Bronto account, and has already figured out how to successfully log in. With no further ado, here’s some example code showing how to add a contact. In my case, I’ve created a Bronto class that allows me to do things easily, and I expect that I’ll add to it as time goes by and our operations get more complicated.

<?php

class Bronto
{
    
    private $_conn = null;
    private $_sessionID = null;
    
    public function __construct()
    {
        // Connect to the Bronto API and tell it to throw SoapExceptions
        $this->_conn = new SoapClient(BRONTO_WSDL, array('exceptions' => true));
        $rs = $this->_conn->login(array(
            'username' => BRONTO_USER,
            'password' => BRONTO_PASS, 
            'sitename' => BRONTO_SITE
        ));
        // Adjust the target URL (in case it's changed) and set the session var in the
        // SOAP header
        $this->_sessionID = $rs->return->sessionId;
        $header = new SoapHeader('http://api.bronto.com', 'sessionHeader', 
            array('sessionId' => $this->_sessionID));
        $this->_conn->__setLocation($rs->return->serviceURL);
        $this->_conn->__setSoapHeaders(array($header));
    }
    
    public function writeContact($email, $format = 'html')
    {
        try {
            // Insert this contact into our account (or update them if they
            // are already there), set them as active, and add them to 
            // a mailing list. Tell Bronto to do these things in insertUpdate mode.
            $rs = $this->_conn->writeContacts(array(
                'contacts' => array(
                    array(
                        'email' => $email,
                        'status' => 'active',
                        'msgPref' => $format,
                        'customSource' => '[source of this contact]',
                        'lists' => array('[mailing list id]')
                    )
                ),
                'handler' => array(
                    'mode' => 'insertUpdate',
                    'listsMode' => 'insertUpdate'
                )
            ));
        } catch (Exception $e) {
            // gracefully handle the error somehow
        }
    }
    
}

?>

Then to actually use this code, assuming you’ve defined BRONTO_WSDL, BRONTO_USER, and BRONTO_PASS somewhere, you do this:

$bronto = new Bronto();
$bronto->writeContact('j.clifton@four-eight-four.com', 'html')

That’s it!

The tough part of this, for me, was figuring out exactly what to pass the writeContacts() SOAP method … even with the documentation. My major issue was figuring out out specify the list I wanted. It’s not clear in the documentation, so first I assumed that I was just passing the list name … but that’s not the case. After blindly trying a few things, I finally figured out that you have to pass it the list id. Finding your lists id is pretty easy … once you’ve connected, just do this (in my example, you’d have to add a function to the Bronto class):

public function dumpListIDs()
{
    header('content-type: text/plain');
    print_r($this->_conn->readLists());
    exit;
}

That will give you something like this for the output:

stdClass Object
(
    [return] => stdClass Object
        (
            [lists] => Array
                (
                    [0] => stdClass Object
                        (
                            [id] => 07d003ec000000000000000000000000abcd
                            [name] => Corporate Clients
                        )

                    [1] => stdClass Object
                        (
                            [id] => 07d003ec0000000000000000000000001234
                            [name] => Main Mailing List
                        )

                    [2] => stdClass Object
                        (
                            [id] => 07d003ec000000000000000000000000ac24
                            [name] => Special Offers
                        )

                )

        )

)

Now … there’s only one problem with this setup. My initial intent was to have the new contact set as unconfirmed, send them an “invitation” so they could confirm their subscription, and add them to the main mailing list. However … if you try to add a contact the way using the method I just demonstrated, but set their status as “unconfirmed”, Bronto complains “Insert requires active status” … so that’s not going to work. So, it’s back to the drawing board for me, until I can figure out my next step (or either contact Bronto support on Monday if I can’t figure it out over the weekend). When I do, I’ll post a follow-up.