Home › Constant Contact Web Service APIs

REST API Reference

Sat, 03/08/2008 - 15:26 — webservices

API How-To Guides

Below you will find guides on how to perform various actions using the API's.  Currently, only the campaigns documentation has been re-written to have separate how-to guide from the API technical reference, but we will be updating the rest of the sections soon.  For now, you will find that links other than those on campaigns point to our existing documentation that combines both how-to guides and API reference.

 

API Reference

The API consists of a set of available API URLs ("Resources") which expose select account access and update data. The API resources are protected by an Authentication Model, described below. This table describes the top level URIs, or resources that are supported:

Service Description
https://api.constantcontact.com/ws/customers/{UserName}/		 The service document. This URI returns information describing the collections that are accessible for the customer identified by UserName.
Contact Lists Collection
https://api.constantcontact.com/ws/customers/{UserName}/lists		 Information about Contact Lists for the customer identified by UserName. This resource is used to discover what Contact Lists exist and to modify and delete Contact Lists.
Contact List Members Collection
https://api.constantcontact.com/ws/customers/{UserName}/lists/{ListId}/members		 The set of Contacts that belongs to a contact list identified by {ListId} for the Account Owner {UserName}. This resource currently allows only the retrieval of a list of Contacts.
Activities Collection (BULK OPERATIONS)
https://api.constantcontact.com/ws/customers/{UserName}/activities		 Batch Contact and download operations, including the ability to add, update or remove sets of Contacts. Upload and download operations on multiple records are performed by batch operations. This Activity resource can be used to submit these batch activities and to access the activities and their results. Currently supported activities include adding contacts to a contact list, updating contact details, removing contacts from a list, clearing a list of all contacts and downloading the contacts in a user or system-defined Contact List.
This resource is also used to check the status of submitted batch jobs. (Note: to upload or unsubscribe individual contacts see the contactsCollection resource.)
Contacts Collection
https://api.constantcontact.com/ws/customers/{UserName}/contacts		 The set of Contacts for the Account Owner {UserName}. This resource can be used to create, retrieve or update a Contact and to associate or disassociate the Contact with Contact Lists. A query parameter can be used to search for a contact with a specified email address.
Campaigns Collection
https://api.constantcontact.com/ws/customers/{UserName}/campaigns		 This resource answers the question, "For this account, what campaigns (emails) exist?" and it provides summary campaign results for sent campaigns.

The resource provies the set of Email Campaigns which exist for the Account Owner {UserName}. For each campaign, information about the Campaign Status (Draft, Scheduled, Sent) is available. For Sent campaigns, summary Campaign Results, including Sends, Opens and Clicks, are available.

Account Settings Email Collection
https://api.constantcontact.com/ws/customers/{UserName}/settings/emailaddresses

 This resource returns a list of email addresses that are registered to an account, specified by {UserName}, and whether they have been confirmed or not.  This resource is typically used in conjunction with campaigns resource to be used as From/Reply-To email addresses.
Contact Events Service
https://api.constantcontact.com/ws/customers/{UserName}/contacts/{ContactId}/events/		 This resource answers the question, "For this Contact what email campaign actions have occurred?"

The resource provides the set of Campaign Events such as 'sends', 'opens', and 'clicks' associated with an individual Contact. For each Contact, the service provides a set of events (Open, Click...). Each Event includes event specific details including timestamp, link details and other related data.
Campaign Events Service
https://api.constantcontact.com/ws/customers/{UserName}/campaigns/{CampaignId}/events/		 This resource answers the question - "For this campaign, which Contacts took action X (Open, Click...)?"

Supported 'actions' (event types) include 'sends', 'opens', and 'clicks'.
The service provides a collection of events (Open, Click...) associated with that Campaign. Each collection includes further details including the Contact that performed the event, the timestamp, and event specific information including link details and other related data.

 

Error Codes

To see a complete list of error codes returned by our API's, you can reference this document.

 

Atom

The Constant Contact Web Services API is based on the Atom Publishing Protocol (Atompub for short), a simple HTTP-based protocol for creating and updating web resources. Atompub is standardized as RFC 5023, and serves as the basis of both Google's GData and Microsoft's ADO.NET Data Services (codename "Project Astoria") web service efforts.

 

Using the API (Authentication and Access)

Accessing the APIs requires use of one of the supported Authentication models. The Authentication models each require:

  • An API Key (aka Consumer Key) which identifies the Application Developer (you) and the Application
  • Permission from the Constant Contact Account holder. Permission may come in the form of an account username and password (for Digest or Basic Authentication) or in the form of an Access Token (for OAuth authentication)
  • An Account Specific URI (The URI used must reflect the Username for the account you are accessing)

Examples showing rudimentary access to information in Constant Contact user accounts are included in the Authentication Details pages referenced from the Authentication Overview.