Washing With SOAP: Part 2

This post only applies to Legacy Version 3 of the API

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. Washing With SOAP: Part 3 This post only applies to Legacy Version 3 of...
2. Washing With SOAP: Part 1 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...

Tagged as: API Legacy Version 3, soap, web service, wsdl, xml