How to Login

Creating an Authenticated Session

All API calls require the existence of an active, authenticated session. The function login() is used to create such a session. You pass an API token to login as credentials to authenticate your access. Upon successful authentication, a sessionId is returned.

The sessionId is a unique id used to identify an API session. API sessions become inactive if no calls are made for 20 minutes. Multiple sessions can be created for a single API token; If you wish to create a threaded application we recommend you create multiple sessions rather than reuse a single session in several threads. Successive calls to login() create a new session with no affect on previously created sessions.

Code Examples

To easily copy the code below, move your mouse to the buttons at the top right corner of the code example. Click View Source or Copy To Clipboard to copy the code below in plain text format without line numbers.

Examples

<?php

/*  
This example script will connect to the API, authenticate a session, 
add a new contact, add a new list, update the contact to be on the 
list, and then read the contact to verify that they are on the list. 
Be sure to replace the "ADD YOUR API TOKEN HERE" text with a working 
API Token.
*/

ini_set("soap.wsdl_cache_enabled", "0");
date_default_timezone_set('America/New_York');

$wsdl = "https://api.bronto.com/v4?wsdl";
$url = "https://api.bronto.com/v4";

$client = new SoapClient($wsdl, array('trace' => 1, 'encoding' => 'UTF-8'));
$client->__setLocation($url);

// Login
$token = "ADD YOUR API TOKEN HERE";
$sessionId = $client->login(array("apiToken" => $token))->return;
$client->__setSoapHeaders(array(new SoapHeader("http://api.bronto.com/v4", 
                                               'sessionHeader',
                                               array('sessionId' => $sessionId))));

// Add our new contact
$contact = array(
	array("email" => "john.doe@example.com")
	);
$result = $client->addContacts(array("contacts" => $contact))->return->results;
if ($result->isError) {
	echo "Unable to add new contact!\n";
	return;
}
echo "Added new contact.\n";

// Add our new list
$list = array(
		array("name" => "My first list", "label" => "Hello Bronto List")
	);
$result = $client->addLists(array("lists" => $list))->return->results;
if ($result->isError) {
	echo "Unable to add new list!\n";
	return;
}
$listId = $result->id;
echo "Added new list.\n";


// Update the contact to put him on the list
$contact = array(
		array("email" => "john.doe@example.com", "listIds" => array($listId))
	);
$result = $client->updateContacts(array("contacts" => $contact))->return->results;
if ($result->isError) {
	echo "Unable to update contact!\n";
	return;
}
echo "Added contact to list.\n";


// Verify the contact is on the list
$filter = array(
	"email" => array(array("operator" => "EqualTo", "value" => "john.doe@example.com"))
);

$result = $client->readContacts(array(
		"filter" => $filter, 
		"includeLists" => true,
		"fields" => null, 
		"pageNumber" => 1
		))->return;
if ($result->listIds != $listId) {
	echo "Contact is not on the list!\n";
	return;
}

echo "Contact is on the list.\n";
?>

/*  
This example will connect to the API, authenticate a session, add 
a new contact, add a new list, update the contact to be on the 
list, and then read the contact to verify that they are on the list. 
Be sure to replace the "ADD YOUR API TOKEN HERE" text with a working 
API Token.
*/

package com.bronto;

import org.apache.axis.client.Stub;

import com.bronto.api.objects.BrontoSoapApi;
import com.bronto.api.objects.BrontoSoapApiImplService;
import com.bronto.api.objects.BrontoSoapApiImplServiceLocator;
import com.bronto.api.objects.ContactFilter;
import com.bronto.api.objects.ContactObject;
import com.bronto.api.objects.FilterOperator;
import com.bronto.api.objects.MailListObject;
import com.bronto.api.objects.StringValue;
import com.bronto.api.objects.WriteResult;

public class HelloBronto {
  private static final String API_TOKEN = "ADD YOUR API TOKEN HERE";

  public static void main(String args[]) throws Exception {
	BrontoSoapApiImplService locator = new BrontoSoapApiImplServiceLocator();
	BrontoSoapApi api = locator.getBrontoSoapApiImplPort();

	// Login
	String sessionId = api.login(API_TOKEN);
	((Stub)api).setHeader(locator.getServiceName().getNamespaceURI(), "sessionId", sessionId);

	// Add our new contact
	ContactObject contact = new ContactObject();
	contact.setEmail("john.doe@example.com");
	WriteResult res = api.addContacts(new ContactObject[] { contact });
	if (res.getErrors() != null) {
		System.out.println("Unable to add new contact!");
		return;
	}
	System.out.println("Added new contact.");

	// Add a new list
	MailListObject list = new MailListObject();
	list.setLabel("My first list");
	list.setName("Hello Bronto List");
	res = api.addLists(new MailListObject[] { list });
	if (res.getErrors() != null) {
		System.out.println("Unable to add new list!");
		return;
	}
	System.out.println("Added new list.");

	// Update the contact to put him on the list
	String listId = res.getResults(0).getId();
	contact.setListIds(new String[] { listId });
	res = api.updateContacts(new ContactObject[] { contact });
	if (res.getErrors() != null) {
		System.out.println("Unable to update contact!");
		return;
	}
	System.out.println("Added contact to list.");

	// Verify the contact is on the list
	ContactFilter filter = new ContactFilter();
	filter.setEmail(new StringValue[] { new StringValue(FilterOperator.EqualTo, "john.doe@example.com") });
	ContactObject[] contacts = api.readContacts(filter, true, null, 1);
	if (!contacts[0].getListIds()[0].equals(listId)) {
		System.out.println("Contact is not on the list!");
		return;
	}

	System.out.println("Contact is on the list.");
  }
}

import sys
import logging
from suds.client import Client
from suds import WebFault

"""
This example script will login to the API, obtain
a session id, and then print the ID and email address
of all contacts whose email address contains the
string 'gmail'. BE SURE TO REPLACE ALL PLACEHOLDER TEXT

Tested with Python 2.6.1 and suds soap library version 0.4

See suds home page:
https://fedorahosted.org/suds/

"""

# Bronto API WSDL
BRONTO_WSDL = 'https://api.bronto.com/v4?wsdl'

# start up basic logging
logging.basicConfig()

# Replace the placeholder text with a valid
# API token
TOKEN = "ADD TOKEN HERE"


# login using the token to obtain a session ID
bApi = Client( BRONTO_WSDL )

try:
       session_id = bApi.service.login(TOKEN)
# Just exit if something goes wrong
except WebFault, e:
  print '\nERROR MESSAGE:'
  print e
  sys.exit()

# Set up the soap headers using the
# session_id obtained from login()
session_header = bApi.factory.create("sessionHeader")
session_header.sessionId = session_id
bApi.set_options(soapheaders=session_header)

# Create the mailListFilter passed into
# readLists()

filter = bApi.factory.create('contactFilter')

stringValue = bApi.factory.create('stringValue')
stringValue.value = 'gmail'
filterOperator = bApi.factory.create('filterOperator')
stringValue.operator = filterOperator.Contains

filterType = bApi.factory.create('filterType')

filter.email = stringValue
filter.type = filterType.AND

# Try calling readContacts. Print email address and ID.
try:
       read_contact = bApi.service.readContacts(filter, includeLists = True, pageNumber = 1)
       for contact in read_contact:
               print 'Contact email: ' + contact.email
               print 'Contact ID: ' + contact.id
except WebFault, e:
       print '\nERROR MESSAGE:'
       print e
       sys.exit()