Constant Contact Labs Developer Blog

CTCT Web Services Python Client Library Posted Wednesday, December 23, 2009 Brendan White 8 Comments
Like the Java Client Library, the Python Client Library provides a simple API to access Constant Contact Web Services, only using Python. Python is a powerful multi-platform language with comprehensive libraries, a interactive shell, and best of all, a short learning curve. This makes the Python Client Library a good choice for quickly creating utilities or applications that leverage Constant Contact’s APIs or for users looking to manage large accounts programmatically. Included in this post are links to the library itself and an overview of its usage with code examples to help you get started.

NOTE: This library is open source and is maintained and supported by the open source developer community only. Constant Contact and Constant Contact Labs will NOT provide support for this library.

Getting The Library

SourceForge:

https://sourceforge.net/projects/ctctwspylib/

Subversion:
```
svn co https://ctctwspylib.svn.sourceforge.net/svnroot/ctctwspylib 
```
Creating the Connection Object

Using the client library starts with creating a CTCTConnection object. You must supply a Constant Contact username and password as well as a Constant Contact developer key. If you don’t have an account you can create one here: And Constant Contact API keys are requested here:
```
API_KEY = "ctctabc-defghi-jklmnop" #not a valid key
mConnection = CTCTConnection(API_KEY, "joe", "password123")
```
Authentication

To authenticate credentials, in this case joe using password123, you might do the following:
```
isValid = mConnection.verify_credentials()

if(isValid):
    #valid credentials
else:
    #invalid credentials
```
Characters outside the character set a-zA-Z0-9.-_@ are not allowed in Constant Contact usernames. Using the library you are able to catch invalid usernames:
```
#make sure to import InvalidUsernameException
from __init__ import CTCTConnection, InvalidUsernameException
    
try:
    isValid = mConnection.verify_credentials()
except InvalidUsernameException, err:  #err contains an appropriate error message
    print str(err)
```
Contact Lists

Retrieve ALL Lists.

Fields returned are:
- id
- name
- updated
Lists NOT returned:
- Removed
- Do Not Mail
- Active
```
#lists will contain a python list of dictionaries, each dictionary contains data for an individual list
lists = mConnection.get_contact_lists()

#print all the list names
for list in lists:
    print list['name']
```
Retrieve Individual List.

Lists are retrieved using the list id.

Fields returned are:
- id
- name
- updated
- opt_in_default
- short_name
- sort_order
```
list_id = '123'
list = mConnection.get_contact_list(list_id)

#print the list name
print list['name']
```
Retrieve List Members

The list members are returned in a python list of dictionaries, each containing individual contact information.

Fields returned are:
- id
- name
- email_address
- updated
```
list_id = '123'
#get the members of list 123
members = mConnection.get_contact_list_members(list_id)

#print the emails of all the members in list 123
for member in members:
    print member['email_address']
```
Creating a New List

To create a new list simply pass a list name.
```
#name of list to create
name = 'My New List'

#create the contact, wasCreated holds success
wasCreated = mConnection.create_contact_list(name)
```
Update a List

Update a list by passing the list id and a python dictionary containing the fields and values to update.
```
#list id to update
list_id = '123'
    
#specify parameters to change
params = {'name': 'New List Name'}

#update the list, wasUpdated holds succecss
wasUpdated = mConnection.update_contact_list(params, list_id)
```
Delete a List

To delete a list use the list id.
```
#list id to delete
list_id = '123'

#delete list 123, wasDeleted holds success
wasDeleted = mConnection.delete_contact_list(list_id)
```
Contacts

Retrieve ALL Contacts

Fields returned are:
- id
- email_address
- email_type
- name
- opt_in_source
- updated
```
#retrieve all the contacts
contacts = mConnection.get_contacts()

#print the email addresses of all contacts
for contact in contacts:
    print contact['email_address']
```
Retrieve Individual Contact

Retrieve detailed information about a contact by providing either a contact email address or a contact id. If both the contact id and email address are available use the id.

Fields returned are:
- id
- updated
- status
- email_address
- email_type
- name
- first_name
- middle_name
- last_name
- job_title
- company_name
- home_phone
- work_phone
- addr1
- addr2
- addr3
- city
- state_code
- state_name
- country_code
- country_name
- postal_code
- sub_postal_code
- note
- custom_field1
- ...
- custom_field15
- contact_lists
```
    
#get the contact by email
contact = mConnection.get_contact(email='joe@sampleaddress.com')
    
#get the contact by id
contact = mConnection.get_contact(contact_id_number='123')
    
#get the contact lists the contact is a member of
lists = contact['contact_lists']
    
#print all the lists ids the contact belongs to
for list_id in lists:
    print list_id
```
Create A Contact

To create a contact supply a dictionary of parameters, keys containting fields to add and corresponding values. Id will be created automatically so do not include it. At least one contact list for the contact to be added to is required.
```
#add the fields
params = {'email_address': 'joe@samplename.com', 'name': 'joe', 'home_phone': '9785554444', 'contact_lists': ['http://api.constantcontact.com/ws/customers/joe/lists/123']}

#create the contact and store success
wasCreated = mConnection.create_contact(params)
```
Update A Contact

Updating an existing contact requires a dictionary of paramaters, fields to change with changed values, and the contact id or contact email address. Again, contact id is preferred.
```
  
#contact id to update
contact_id = '123'

#fields to update, note that new fields can also be added this way
params = {'name': 'joey', 'home_phone': '9783334545', 'city': 'New York'}

#update the contact using the contact id, and store success
wasUpdated = mConnection.update_contact(params, contact_id_number=contact_id)

#update the contact using an email address, ..
wasUpdated = mConnection.update_contact(params, email='joe@samplename.com')
```
Deleting A Contact

To delete a contact all that is needed is the contact id or email address of the contact.
```
  
#contact id to delete
contact_id = '123'

#delete the contact using the contact id (preferred)
wasDeleted = mConnection.delete_contact(contact_id_number=contact_id)

#delete the contact using the email address
wasDeleted = mConnection.delete_contact(email='joe@samplename.com') 
```
Retrieve Contact Events

To retrieve events for a contact specify the contact either by email address or contact id and the event type. Event type is an enumeration of the CTCTConnection class.

Event types are:
- EVENTS_BOUNCES (0)
- EVENTS_CLICKS
- EVENTS_FORWARDS
- EVENTS_OPENS
- EVENTS_OUT_OUTS
- EVENTS_SENDS (5)
```
    
#get the number of bounce events for contact 123
bounce_events = mConnection.get_contact_events(event_type=CTCTConnection.EVENTS_BOUNCES, contact_id_number=123)
    
#get the number of opens for .(JavaScript must be enabled to view this email address)
open_events = mConnection.get_contact_events(event_type=CTCTConnection.EVENTS_OPENS, email='joe@samplename.com')
```
Campaigns

Retrieve ALL Campaigns

To retrieve all campaigns specify the type of campaigns to be returned. If no campaign type is specified, ALL will be returned. A python list of campaigns will be returned and each campaign in campaigns is a dictionary containing fields and values for each individual campaign.

Fields returned are:
- id
- name
- status
- date
- updated
Campaign type is an enumeration of the CTCTConnection class.

Campaign types are:
- CAMPAIGNS_ALL (0)
- CAMPAIGNS_DRAFT
- CAMPAIGNS_RUNNING
- CAMPAIGNS_SENT
- CAMPAIGNS_SCHEDULED (4)
```
    
#get all sent campaigns
sent_campaigns = mConnection.get_campaigns(type=CTCTConnection.CAMPAIGNS_SENT)
    
#print the date for all sent campaigns
for campaign in sent_campaigns:
    print campaign['date']
```
Get An Individual Campaign

To retrieve an individual campaign just pass the campaign id. A dictionary containing the invidual campaign data will be returned.

Fields returned are:
- id
- updated
- status
- name
- date
- last_edit_date
- last_run_date
- sent
- opens
- clicks
- bounces
- forwards
- opt_outs
- spam_reports
- contact_lists
- urls
```
campaign_id = '1234567890123'
   
#get the campaign by id
campaign = mConnection.get_campaign(campaign_id_number=campaign_id)
   
#print the campaign name
print 'The Campaign Name is ' + campaign['name']
   
#print the contact lists associated with the email campaign
lists = campaign['contact_lists']
for list in lists:
    print list['id']
       
#print the campaign-included urls clicks tracking information
urls = campaign['urls']
for url in urls:
    print url['clicks']
```
Get Campaign Events

To retrieve events for a campaign specify the campaign id and the event type. Event type is an enumeration of the CTCTConnection class.

Event types are:
- EVENTS_BOUNCES (0)
- EVENTS_CLICKS
- EVENTS_FORWARDS
- EVENTS_OPENS
- EVENTS_OUT_OUTS
- EVENTS_SENDS (5)
```
#get the bounce events for the campaign
bounce_events = mConnection.get_campaign_events('123456789123', CTCTConnection.EVENTS_BOUNCES)    
   
#get the total sends for the campaign
sent = mConnection.get_campaign_events('12345678123', CTCTConnection.EVENTS_SENDS)
```
Activities

Retrieve ALL Activities

Fields returned are:
- id
- updated
- type
- status
- errors
- file_name
- transaction_count
- run_start_time
- run_finish_time
- insert_time
```
   
#get all activities
activities = mConnection.get_activities()
    
#print the status for all activities
for activity in activities:
    print activity['status']
```
Get An Individual Activity

To retrieve an individual activity just pass the activity id. A dictionary containing the invidual activity data will be returned.

Fields returned are:
- id
- updated
- type
- status
- errors
- file_name
- transaction_count
- run_start_time
- run_finish_time
- insert_time
```
  
#not a real activity id, for example
activity_id = '1234567890123'
    
#get the individual activity
activity = mConnection.get_activity(activity_id_number=activity_id)
    
#print the errors for the activity if there are any
errors = activity['errors']
for error in errors:
    print error
```
Creating an Add Contacts / Remove Contacts Activity

To create an Add or Remove Contacts activity you must supply a type (Add or Remove), the lists you would like to add to or remove from, and the actual contact data to be added or removed. The activity id is returned or None if it was unsuccessful

The types are: ADD_CONTACTS, SV_ADD, ADD_CONTACT_DETAIL, REMOVE_CONTACTS_FROM_LISTS. Constant Contact will decide which Add to use depending on the data so using any of the three add types will yield the same result. To remove contacts from lists use REMOVE_CONTACTS_FROM_LISTS.

The data has to be supplied in a tabular format. The first row is always the column names and each row after that is the data for each contact in the same order as the supplied columns. For example:

EMAIL ADDRESS, FIRST NAME, LAST NAME
.(JavaScript must be enabled to view this email address), Joe, Smith
.(JavaScript must be enabled to view this email address), Jane, Smith
...

In python, there is a dictionary containting a key columns and a key rows that contain the values in python lists. The lists will contain the column data and row data respectively.
```
 
#lists contacts will be added to
lists = ['http://api.constantcontact.com/ws/customers/username/lists/1', 'http://api.constantcontact.com/ws/customers/username/lists/2']
    
#data to be added to the lists, email address, first name
data = {'columns': ['EMAIL ADDRESS', 'FIRST NAME'], 'rows': ['num1@email.com', 'Joe']}
    
#create the add contact activity, the activity id is returned if successful
activity_id = mConnection.create_activity(type='SV_ADD', lists=lists, data=data)
    
#check the activity status
activity = mConnection.get_activity(activity_id_number=activity_id)
print activity['status']
```
Creating a Clear Contacts Activity

A Clear Contacts activity is different than a Remove Contacts activity. It will clear all contacts from a list or lists. To create the activity just supply the lists to be cleared. The activity id is returned.
```
 
#lists to clear
lists = ['http://api.constantcontact.com/ws/customers/username/lists/1', 'http://api.constantcontact.com/ws/customers/username/lists/1']

#create clear contacts activity
activity_id = mConnection.create_activity(type='CLEAR_CONTACTS_FROM_LISTS', lists=lists)
    
#check the activity status
activity = mConnection.get_activity(activity_id_number=activity_id)
print activity['status']
```
Creating a Export Contacts Activity

A Export activity exports contacts from a list or lists to a txt or csv file. To create the activity just supply the type of EXPORT_CONTACTS and a list to export. Additionally you can also supply options which are passed in the ‘data’ parameter. Options are dictionary entries with the key being the keynames below and the corresponding value options.

Options (defaults are bold):
fileType (csv or txt)
exportOptDate (true or false)
exportOptSource (true or false)
exportListName (true or false)
sortBy (EMAIL_ADDRESS, DATE_DESC)
columns (FIRST NAME, MIDDLE NAME, LAST NAME, etc…
complete list see http://developer.constantcontact.com/doc/activities)
```
#the list to export
lists = {'list_id': 'http://api.constantcontact.com/ws/customers/username/lists/1'}
        
#the columns to export, email address is always exported by default
data = {'columns': ['First Name', 'Last Name']}
        
#create an export activity as a csv file sorting the columns by date descending
activity_id = mConnection.create_activity(type='EXPORT_CONTACTS', lists=lists, data=data)
        
#check the activity status
activity = mConnection.get_activity(activity_id_number=activity_id)
print activity['status']
```
The opinions expressed here represent those of the author and not those of Constant Contact, Inc. Read Blog Terms
Share

| More

Tags
Libraries • Open Source • Python • Web Services

Next Post Previous Post

Comments (8) +comment on this post

Elf M. Sternberg | 2:54 PM January 19, 2010

Hey, Huan, I’ve been trying to use the library, and it’s a mess. The get_contact_list_members is looking for a string that’s not returned in the atom retreived, and while all my addresses through my login at constant contract are valid, I’m getting a lot of None values for email addresses.

Is there any initiative to update the ctctwspylib.py library to match the output of your ws anytime soon?
Huan Lai | 1:23 PM January 20, 2010

Hello there Elf,

Do you mind posting the code that you used? I just did a quick test of the code from SourceForge and it seemed to work fine. Perhaps there is a bug that we missed, or the documentation is lacking.

Thank you,
Huan Lai
Brendan White | 2:22 PM January 20, 2010

Elf,

After testing on multiple accounts we haven’t run into any problems using that particular function. To get through the problem you are having it’s best to submit a bug to the library on SourceForge.net. It will be easier for you to provide more information (including files) using that system than our comments section, and your bug (if it is a bug) may be fixed sooner if it is available to the open-source community.

Submitting A Bug:

1. Navigate to: http://sourceforge.net/projects/ctctwspylib/support
2. Click on the link “Bugs” toward the bottom of the page under “Project Trackers”
3. Toward the top of the page find the link titled “Add new” and click it
4. Add as much information regarding the bug and upload any helpful files
5. Click “Add artifact” to submit the bug

Also, at this time there is no plan to update the library to match the output of the CTCT WebServices.
David | 7:56 PM February 17, 2010

Are there plans to add support to create campaigns via the python client lib?
Brendan White | 6:11 PM February 18, 2010

Hi David,

Thanks for the comment. Eventually we would like to support all our web services functionality in the library, but at this time there is no formal plan for the Labs to add support for creating campaigns via the Python Client Library. That being said we are not the only contributors to the library. There is always the chance a developer from the open source community will add that support before we do.

The best thing to do is add a feature request to the project page so that other contributing developers can view your request. To post a feature request follow the link in step 1 of “Submitting A Bug” in the comment above, Click “Feature Requests” toward the bottom of the page under “Project Trackers”, and then follow steps 3 - 5 to submit.
Oleg K | 2:10 PM September 17, 2010

there is a bug at line 800 in __init__.py “campaigns.extend(self.get_campaigns(next_path))”
should be
“campaigns.extend(self.get_campaigns(path=next_path))”

otherwise it will request same page ower and ower again, instead next page
Collin Anderson | 5:17 PM December 2, 2010

I submitted a bug. http://sourceforge.net/tracker/?func=detail&aid=3125968&group_id=291725&atid=1233429
Mobley Hobbs | 5:52 PM April 7, 2011

Get Your Spring Carpet Clean Today.

Add your comment below

* Please be aware that all comments are moderated.

Interested in a particular topic?

If there are specific topics you’d like to see us discuss on our blog or other ideas you’d like to share, please let us know. Click here to contact us.

Follow Us

Join our mailing list

Constant Contact Labs Developer Blog

CTCT Web Services Python Client Library Posted Wednesday, December 23, 2009 Brendan White 8 Comments

Getting The Library

SourceForge:

Subversion:

Creating the Connection Object

Authentication

Contact Lists

Retrieve ALL Lists.

Retrieve Individual List.

Retrieve List Members

Creating a New List

Update a List

Delete a List

Contacts

Retrieve ALL Contacts

Retrieve Individual Contact

Create A Contact

Update A Contact

Deleting A Contact

Retrieve Contact Events

Campaigns

Retrieve ALL Campaigns

Get An Individual Campaign

Get Campaign Events

Activities

Retrieve ALL Activities

Get An Individual Activity

Creating an Add Contacts / Remove Contacts Activity

Creating a Clear Contacts Activity

Creating a Export Contacts Activity

Share

Tags

Comments (8) +comment on this post

Elf M. Sternberg | 2:54 PM January 19, 2010

Huan Lai | 1:23 PM January 20, 2010

Brendan White | 2:22 PM January 20, 2010

David | 7:56 PM February 17, 2010

Brendan White | 6:11 PM February 18, 2010

Oleg K | 2:10 PM September 17, 2010

Collin Anderson | 5:17 PM December 2, 2010

Mobley Hobbs | 5:52 PM April 7, 2011

Add your comment below

Categories

Popular blog posts

Recent comments

Archives

Join our mailing list

Interested in a particular topic?