Atom

Atom and Atompub

Atom consists of two parts:

The Atom Publishing Protocol (AtomPub)

is an application-level protocol
for publishing and editing Web resources. The protocol is based on HTTP
transfer of Atom-formatted representations. It is specified in
RFC 5023.

The Atom Syndication Format

is an XML-based Web content and metadata
syndication format. It is specified in
RFC 4287.

The Web Service API uses Atom-formatted XML documents to transfer data and
Atompub as the protocol that specifies how to create, retrieve, update and delete the
Atom-formatted resources.

Data Format

The Web Service API represents individual items of data as Atom
Entries
and collections of items as Atom
Feeds.
Within an Entry, a data item is stored as an XML document within the Entry's
Content element.
Additional information is stored in other Atom elements,
and can be used for tasks like paging through a Feed.

Atom content Element

The API stores each entry's data as a well-formed XML fragment inside the
content element. The element's type attribute has a value of
"application/vnd.ctct+xml". All of the XML is in the
http://ws.constantcontact.com/ns/1.0/ namespace.

The fragment's top-level element indicates the type of the entry, e.g.
ContactList or Activity. The top-level element
also has an id attribute. Its value serves as a unique identifier
for the entry, and can be used to refer to the entry. Each property of the entry
is represented as an element and value inside the top-level element.

Other Atom Elements

Some required Atom element values are populated with values from the underlying
Constant Contact data. For example, in a Contact List entry, the Atom title
element contains the list's name. These values are populated for convenience when
using Atom-aware tools, and because they are required by the Atom specification.
The definitive value is always that in the XML fragment inside the Atom
content element. In particular, on create and update operations values are
always read from the content XML.

Paging and Links

Collections may contain large numbers of entries. To avoid problems with handling large
amounts of data with a single request, the server may elect to provide paged collections.
When it does, it will return an Atom feed containing a subset of the data along
with a link to get the next chunk of data. Specifically,the feed will contain Atom
link elements with rel attributes indicating what the
link is pointing to.

<feed xmlns="http://www.w3.org/2005/Atom">
  ...
  <link href="lists?next=50" rel="next" />
  <link href="lists" rel="first" />
  <link href="lists?next=25" rel="current" />
  <entry>
    ...
  </entry>
  ...
</feed>

In the example above, the first link element has rel="next",
indication that it points to the next page of the collection. The other two links point
to the first and current pages respectively. All links are relative to the current document.

Protocol

This article
gives a good introduction to Atompub.

Service Document

The service document describes the resources available for a particular account. Each Constant Contact account has its own service document because the resources available may vary depending on which applications the account uses and what permissions have been granted to the application using the API.

The service document is retrieved by issuing an HTTP GET to the account's Base URI. The Base URI is http://api.constantcontact.com/ws/customers/{UserName}/, where {UserName} is the account owner's Constant Contact user name. The {UserName} value must be in lower case, and any character(s) that are not permitted in a URI must be escaped. (Most languages/platforms have a function to do the escaping; in Javascript, it's encodeURIComponent(), in .NET, it's System.Web.HttpUtility.UrlEncode(), in PHP it's urlencode() and in Java, it's java.net.URLEncoder.encode().)

Example

Here is a service document for an account with the user name joesflowers. This document could be retrieved by doing an HTTP GET on http://api.constantcontact.com/ws/customers/joesflowers/ and presenting the proper credentials:

<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title type="text">Constant Contact Web Services Customer Workspace</atom:title>
    <collection href="/ws/customers/joesflowers/lists">
      <atom:title type="text">Contact Lists</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/activities">
      <atom:title type="text">Bulk Activity</atom:title>
      <accept>application/x-www-form-urlencoded</accept>
      <accept>multipart/form-data</accept>
    </collection>
  </workspace>
</service>

In Atom terminology, a service document describes a Workspace. This one describes the Constant Contact Web Services Customer Workspace. This workspace contains two Collections, called Contact Lists and Bulk Activity. For each collection, the href attribute specifies the collection's URI and the accept element(s) specify the type(s) of documents the collection will accept when creating a new entry. Section 8 of RFC 5023 describes the format of a service document in detail. The documentation page for each collection type will describe the detailed HTTP request and response formats.

Contact Lists Collection

The Contact Lists collection is used to list, create, modify and delete Contact Lists. Contact Lists are names for groups of Contacts. The Contact Lists collection manipulates the lists themselves. It does not perform any operations on a list's member Contacts.

Retrieving a Collection

To retrieve the collection of contact lists for the UserName joesflowers, you perform an HTTP GET on the collection URI, http://api.constantcontact.com/ws/customers/joesflowers/lists in this example, which returns the following XML document: 

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists</id>
  <title type="text">Contact Lists</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>Constant Contact Web Services</name>
  </author>
  <updated>2008-04-16T13:07:13.453Z</updated>
  <link href="lists?next=6" rel="next" />
  <link href="lists" rel="first" />
  <link href="lists" rel="current" />
  <entry>
    <link href="/ws/customers/joesflowers/lists/1" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/1</id>
    <title type="text">General Interest</title>
    <updated>2008-04-16T13:07:14.057Z</updated>
    <content type="application/vnd.ctct+xml">
      <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
          id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
        <OptInDefault>false</OptInDefault>
        <Name>General Interest</Name>
        <ShortName>General Interest</ShortName>
        <SortOrder>1</SortOrder>
      </ContactList>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/lists/2" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/2</id>
    <title type="text">Recent Signups</title>
    <updated>2008-04-16T13:07:14.061Z</updated>
    <content type="application/vnd.ctct+xml">
      <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
          ?id="http://api.constantcontact.com/ws/customers/joesflowers/lists/2">
        <OptInDefault>false</OptInDefault>
        <Name>Recent Signups</Name>
        <ShortName>Recent Signups</ShortName>
        <SortOrder>2</SortOrder>
      </ContactList>
    </content>
  </entry>
</feed>

The response is made up of a feed element which contains some metadata about the feed followed by a series of entry elements. Each entry is made up of some metadata followed by a content element. Inside the content element is a ContactList element which describes the attributes of a particular contact list. The structure of the Atom elements is described in detail by RFC 4287. The structure of the ContactList element is described below.

Retrieving an Individual List

An individual list entry may be retrieved by issuing an HTTP GET to the entry's URI. The URI may be obtained from the Location header after creating a new entry or from the link element with rel="edit" attribute in an existing entry. A typical entry looks like this: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/lists/1" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/1</id>
  <title type="text">General Interest</title>  
  <updated>2008-04-16T18:39:35.710Z</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
        id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
      <OptInDefault>false</OptInDefault>
      <Name>General Interest</Name>
      <ShortName>General Interest</ShortName>
      <SortOrder>1</SortOrder>
    </ContactList>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/lists</id>
    <title type="text">Contact Lists</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>Constant Contact Web Services</name>
    </author>
    <updated>2008-04-16T18:39:35.717Z</updated>
  </source>
</entry>

Creating a New List

A new Contact list is created by making an HTTP POST to the collection URI. The POST body must contain an Atom entry element that includes the content for the new list.   The Content-Type of the request must be set to application/atom+xml.  Here is a representative entry: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>data:,</id>
  <title/>
  <author/>
  <updated>2008-04-16</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/">
      <OptInDefault>false</OptInDefault>
      <Name>A New List</Name>
      <SortOrder>99</SortOrder>
    </ContactList>
  </content>
</entry>

Note that the id, title, author and updated elements must be present in the XML in order to conform to the Atom specification, even though their values will be replaced by the server. The <id> element must have an acceptable format (<id>data:,<id> will work). The title and author elements may be empty. The id must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness. The updated element must contain a date or date/time value, but again the value is not used by the server.

If the new list is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created List, and the entity body returned will be the entry for the list, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/lists/15</id>
  <title type="text">A New List</title>
  <author />
  <updated>2008-04-16T15:28:09.757Z</updated>
  <content type="application/vnd.ctct+xml">
    <ContactList xmlns="http://ws.constantcontact.com/ns/1.0/" 
        id="http://api.constantcontact.com/ws/customers/joesflowers/lists/15">
      <OptInDefault>false</OptInDefault>
      <Name>Test list 5</Name>
      <SortOrder>1</SortOrder>
      <ShortName>Test list 5</ShortName>
    </ContactList>
  </content>
  <link href="/ws/customers/joesflowers/lists/15" rel="edit" />
</entry>

Updating a List

A Contact List is updated by issuing an HTTP PUT to the entry's URI. The PUT body must contain an Atom entry element with the changed content for the list.

The Atom entry must include an <id> tag and that id must reflect the URI of the list you are updating, for example, if you want to update the list in the 'Create' example above, this line is required:
<id>http://api.constantcontact.com/ws/customers/joesflowers/lists/15</id>

As a general rule, your "PUT" entry should include all of the content you receive in "GET" for the resource you are updating. It may be simplest to "GET" the resource you would like to update, then change only the fields you want to update and "PUT" the updated resource back. The API will ignore read only fields (such as update time) and your entry will be complete.

Clearing All Contacts From a List

To clear all contacts from a list, you need to create a bulk activity to do.  Please refer to the bulk activity documentation for more details.

Deleting a List

A Contact List is deleted by issuing an HTTP DELETE to the entry's URI. The call will return 204 No Content if it succeeds.

Contact List Data Format

Bulk Activity: Collection of Activities

Constant Contact encourages the use of asynchronous background jobs to manage large collections of data. The Bulk Activity collection is used to create and manage those jobs, called Activities. Currently, the collection allows you to create jobs to add, remove and download contacts from contact lists. It also allows you to check the status of a customer's activities and to see when an activity is completed and whether it succeeded or failed. A single "call" to the "Activities" resource generally operates on a set of contacts. The data for that set of contacts is held in a formatted file, described below.

The Activities resource is designed to be used only with large sets of contacts (ie. 25 or more). To manage individual contacts or small sets of contacts, use the Contacts Collection API resource. (As discussed in the Constant Contact API Terms and Conditions, intentional and unintentional misuse of this bulk API to frequently manage individual contacts or small sets of contacts is subject to API access or account termination).

Retrieving a Collection of Activities

To retrieve the collection of activities for the UserName joesflowers, you perform an HTTP GET on the collection URI, https://api.constantcontact.com/ws/customers/joesflowers/activities. For the fictional joesflowers in this example, this returns the following XML document, showing a single activity: 

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
  <title type="text">Bulk Activity</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-04-29T19:31:00.545Z</updated>
  <entry>
    <link href="/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd</id>
    <title type="text"></title>
    <updated>2008-04-29T19:30:15.637Z</updated>
    <content type="application/vnd.ctct+xml">
      <Activity xmlns="http://ws.constantcontact.com/ns/1.0/"
        id="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjxffmvj6qd">
        <Type>ADD_CONTACT_DETAIL</Type>
        <Status>COMPLETE</Status>
        <Errors>
          <Error>
            <LineNumber>3</LineNumber>
            <EmailAddress>test2@test.com</EmailAddress>
            <Message>Unknown US/Canadian state/prov "Test2"</Message>
          </Error>
          <Error>
            <LineNumber>4</LineNumber>
            <EmailAddress>test3@test.com</EmailAddress>
            <Message>Unknown US/Canadian state/prov "Test3"</Message>
          </Error>
        </Errors>
        <FileName></FileName>
        <TransactionCount>1</TransactionCount>
        <RunStartTime>2008-06-25T15:48:01.615Z</RunStartTime>
        <RunFinishTime>2008-06-25T15:48:03.040Z</RunFinishTime>
        <InsertTime>2008-06-25T15:47:37.199Z</InsertTime>
      </Activity>
    </content>
  </entry>
</feed>

The response is made up of a feed element which contains some metadata about the feed followed by a series of entry elements. Each entry is made up of some metadata followed by a content element. Inside the content element is a Activity element which describes the attributes of a particular activity. The structure of the Activity element is described below.

Retrieving the Details of an Individual Activity

An individual activity entry may be retrieved by issuing an HTTP GET to the entry's URI. The URI may be obtained from the Location header after creating a new entry or from the link element with rel="edit" attribute in an existing entry. A typical entry looks like this: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:36:10.948Z</updated>

  <content type="application/vnd.ctct+xml">
    <Activity xmlns="http://ws.constantcontact.com/ns/1.0/"
      id="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz">
      <Type>ADD_CONTACT_DETAIL</Type>
      <Status>COMPLETE</Status>
      <Errors>
        <Error>
          <LineNumber>3</LineNumber>
          <EmailAddress>test2@test.com</EmailAddress>
          <Message>Unknown US/Canadian state/prov "Test2"</Message>
        </Error>
        <Error>
          <LineNumber>4</LineNumber>
          <EmailAddress>test3@test.com</EmailAddress>
          <Message>Unknown US/Canadian state/prov "Test3"</Message>
        </Error>
      </Errors>
      <FileName></FileName>
      <TransactionCount>1</TransactionCount>
      <RunStartTime>2008-04-29T19:36:08.894Z</RunStartTime>
      <RunFinishTime>2008-04-29T19:36:10.948Z</RunFinishTime>
      <InsertTime>2008-04-29T19:35:54.923Z</InsertTime>
    </Activity>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
    <title type="text">Bulk Activity</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-04-29T19:45:24.131Z</updated>
  </source>
</entry>

Creating an Add Contacts/Remove Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'. 

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to upload the Email Address, First Name and Last Name of three contacts (Fred Test, Joan Test and Ann Test) to two Contact Lists in the joesflowers account. Note that the three contacts are submitted in a single invocation of the Activities resource.

  activityType=SV_ADD
  &data=Email+Address%2CFirst+Name%2CLast+Name%0A
  wstest3%40example.com%2C+Fred%2C+Test%0A
  wstest4%40example.com%2C+Joan%2C+Test%0A
  wstest5%40example.com%2C+Ann%2C+Test
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F5
  

application/x-www-form-urlencoded Parameters

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

If the new activity is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:35:54.923Z</updated>
</entry>

Creating a Clear Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

The "Clear Contacts" function works like the "Remove" function, except that you don't have to provide a list of email addresses that you wish to remove.  Select the lists you wish to clear carefully. If you clear contacts from all lists, you will not have any contacts left in your Constant Contact account.

You should refrain from additional operations on the list you are clearing until the job is complete. For example, adding contacts to the list before the clear contacts activity is complete may result in those new contacts being cleared when the activity is run.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'.

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to clear two contact lists, identified by ID's 2 and 5. Note that two contact lists are submitted in a single invocation of the Activities resource.

  activityType=CLEAR_CONTACTS_FROM_LISTS
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2
  &lists=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F5
  

application/x-www-form-urlencoded Parameters

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

If the new activity is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1ffaxjyffmvqgiz</id>
  <title type="text"></title>
  <updated>2008-04-29T19:35:54.923Z</updated>
</entry>

Creating an Export Contacts Activity

A new Activity is created by making an HTTP POST to the activity collection URI. In contrast to the Contact List, the Activity POST body is not an Atom Entry. Instead it is several named parameters encoded with one of the HTML FORM content types, either application/x-www-form-urlencoded or multipart/form-data. So the data passed in the POST body is the same as that produced by a FORM with the ENCTYPE attribute set to that type.

Constructing an application/x-www-form-urlencoded Request

The basics of how to construct an application/x-www-form-urlencoded request are simple:

1. Parameter names and values are escaped. Space characters are replaced by `+', and then reserved characters are escaped as described in [RFC1738], section 2.2: Non-alphanumeric characters are replaced by `%HH', a percent sign and two hexadecimal digits representing the ASCII code of the character. Line breaks are represented as "CR LF" pairs (i.e., `%0D%0A').
2. The parameter name is separated from the value by `=' and name/value pairs are separated from each other by `&'.
3. To use paramter values that contain delimiter characters, such as a comma, you need to enclose the value in double quotes, then encode the value.  For example, to use a parameter value of 'Boston, MA', you need to use '%22Boston%2C%20MA%22'.

Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an application/x-www-form-urlencoded request are in the HTML specification.

The following example shows the parameters used to export the Email Address, First Name and Last Name of three contacts (Fred Test, Joan Test and Ann Test) from a list in the joesflowers account.

    activityType=EXPORT_CONTACTS&fileType=CSV&exportOptDate=true&exportOptSource=true
    &exportListName=true&sortBy=DATE_DESC
    &columns=EMAIL%20ADDRESS&columns=FIRST%20NAME&columns=LAST%20NAME
    &listId=http%3A%2F%2Fapi.constantcontact.com%2Fws%2Fcustomers%2Fjoesflowers%2Flists%2F2
  

application/x-www-form-urlencoded Parameters

Constructing a multipart/form-data Request

When using FORMs, you must use enctype="multipart/form-data" when using <input type="file">. Similarly, when uploading a complete file of data, particularly binary data like MS Excel spreadsheets, you must use a multipart/form-data request. Most programming languages have libraries that implement some or all of the encoding process. The parameters and their values are described in the table below. More details on how to make an multipart/form-data request are in the HTML specification and RFC 2388.

multipart/form-data Parameters

If the new activity is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created activity, and the entity body returned will be the minimal entry for the activity, including server-generated values like ids and links.

After the system has finished processing the Export activity, retrieving the activity entry will return a complete entry that includes the status of the job. If the job completed successfully, it will also contain a link to the exported file. See the example below: 

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp</id>
  <title type="text">EXPORT_CONTACTS: http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1...
  <updated>2008-06-27T13:10:59.944Z</updated>
  <content type="application/vnd.ctct+xml">
    <Activity xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp">
      <Type>EXPORT_CONTACTS</Type>
      <Status>COMPLETE</Status>
      <FileName>http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp.csv</FileName>
      <TransactionCount>0</TransactionCount>
      <Errors></Errors>
      <RunStartTime>2008-06-27T13:10:59.321Z</RunStartTime>
      <RunFinishTime>2008-06-27T13:10:59.944Z</RunFinishTime>
      <InsertTime>2008-06-27T13:10:57.349Z</InsertTime>
    </Activity>
  </content>
  <link href="http://api.constantcontact.com/ws/customers/joesflowers/activities/a07e1gpfcd3fhysynnp.csv" rel="edit-media" />
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/activities</id>
    <title type="text">Activity Collection for customer: joesflowers</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-06-27T16:29:26.723Z</updated>
  </source>
</entry>

Updating an Activity

Activity updates are not currently permitted.

Deleting an Activity

Activity deletes are not currently permitted.

Activity Data Format

Contacts Collection (find, create, modify or delete individual contacts)

The Contacts collection is used to list, create, modify and delete Contacts (also known as subscribers) and to associate and disassociate Contacts and Contact Lists.

The Contacts collection resource is designed to be used only with small sets of contacts (ie. 24 or less). To manage large groups of contacts, use the Activities API resource. (As discussed in the Constant Contact API Terms and Conditions, intentional and unintentional misuse of this discrete API to frequently manage large sets of contacts is subject to API access or account termination).

Retrieving a Collection

To retrieve the collection of contacts for the UserName joesflowers, you perform an HTTP GET on the collection URI, http://api.constantcontact.com/ws/customers/joesflowers/contacts in this example, which returns the following XML document:

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
  <title type="text">Contacts for Customer joesflowers</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-07-15T17:40:28.374Z</updated>
  <link href="/ws/customers/joesflowers/contacts?next=fihuckra" rel="next" />
  <link href="/ws/customers/joesflowers/contacts" rel="first" />
  <link href="/ws/customers/joesflowers/contacts" rel="current" />
  <entry>
    <link href="/ws/customers/joesflowers/contacts/1806" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1806</id>
    <title type="text">Contact: u92204@example.com</title>
    <updated>2008-07-15T17:40:28.544Z</updated>
    <content type="application/vnd.ctct+xml">
      <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1806">
        <Status>Active</Status>
        <EmailAddress>u92204@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name></Name>
        <OptInTime>2008-07-15T15:14:53.219Z</OptInTime>
        <OptInSource>ACTION_BY_CONTACT</OptInSource>
      </Contact>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/contacts/1805" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1805</id>
    <title type="text">Contact: u89439@example.com</title>
    <updated>2008-07-15T17:40:28.548Z</updated>
    <content type="application/vnd.ctct+xml">
      <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1805">
        <Status>Active</Status>
        <EmailAddress>u89439@example.com</EmailAddress>
        <EmailType>HTML</EmailType>
        <Name></Name>
        <OptInTime>2008-07-15T15:14:51.172Z</OptInTime>
        <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
      </Contact>
    </content>
  </entry>
</feed>

The response is made up of a feed element which contains some metadata about the feed followed by a series of entry elements. Each entry is made up of some metadata followed by a content element. Inside the content element is a Contact element which describes some of the important attributes of a particular contact.

Note that in order to get all the data about a particular contact, you must get the individual entry, which contains the complete entry data.

The structure of the Atom elements is described in detail by RFC 4287. The structure of the Contact element is described below.

Querying the Contacts Collection

To find particular Contacts you can query the collection by adding a query parameter to the collection's URI. So to look up the entry for the Contact with email address u89439@example.com, you would GET http://api.constantcontact.com/ws/customers/joesflowers/contacts?email=u89439%40example.com. (Note that the '@' sign in the email address must be properly URL encoded.) If a contact with that email exists, the query will return a feed containing the Contact entry for that email address, including a reference to the URI for the Contact details. If no Contact with that email address exists, the API will return either a 500 error (Server Error) code or will return an empty feed (i.e. a feed with no entries).

You can find multiple contacts with a single query by simply adding additional parameters: http://api.constantcontact.com/ws/customers/joesflowers/contacts?email=u89439%40example.com&email=u10432%40example.com. Just like before, the returned feed will contain entries for any Contacts that are found. Any that don't exist will simply be skipped.

Note that the email must be an exact match, including case! Since all email addresses in Constant Contact are stored in lowercase, please lowercase the email address you use for your query parameter.

The email parameter is the only query currently supported. More query types may be added in the future.

Retrieving an Individual Contact

An individual Contact entry may be retrieved by issuing an HTTP GET to the entry's URI. The URI may be obtained from the Location header after creating a new entry or from the link element with rel="edit" attribute in an existing entry.

If you don't have a link to an entry, you can find it by querying the collection.

A typical entry looks like this:

<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/contacts/1454" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/1454</id>
  <title type="text">Contact: u86597@example.com</title>
  <updated>2008-06-23T06:46:30.078Z</updated>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1454">
      <Status>Active</Status>
      <EmailAddress>u86597@example.com</EmailAddress>
      <EmailType>HTML</EmailType>
      <Name>First Last</Name>
      <FirstName>First</FirstName>
      <MiddleName></MiddleName>
      <LastName>Last</LastName>
      <JobTitle></JobTitle>
      <CompanyName></CompanyName>
      <HomePhone></HomePhone>
      <WorkPhone></WorkPhone>
      <Addr1></Addr1>
      <Addr2></Addr2>
      <Addr3></Addr3>
      <City></City>
      <StateCode></StateCode>
      <StateName></StateName>
      <CountryCode></CountryCode>
      <CountryName></CountryName>
      <PostalCode></PostalCode>
      <SubPostalCode></SubPostalCode>
      <Note></Note>
      <CustomField1></CustomField1>
      <CustomField2></CustomField2>
      <CustomField3></CustomField3>
      <CustomField4></CustomField4>
      <CustomField5></CustomField5>
      <CustomField6></CustomField6>
      <CustomField7></CustomField7>
      <CustomField8></CustomField8>
      <CustomField9></CustomField9>
      <CustomField10></CustomField10>
      <CustomField11></CustomField11>
      <CustomField12></CustomField12>
      <CustomField13></CustomField13>
      <CustomField14></CustomField14>
      <CustomField15></CustomField15>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/lists/1" rel="self" />
          <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
          <OptInTime>2008-06-23T06:46:30.000Z</OptInTime>
        </ContactList>
      </ContactLists>
      <Confirmed>false</Confirmed>
      <InsertTime>2008-06-23T06:46:29.984Z</InsertTime>
      <LastUpdateTime>2008-06-23T06:46:30.078Z</LastUpdateTime>
    </Contact>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts</id>
    <title type="text">Contacts for Customer joesflowers</title>
    <link href="" />
    <link href="" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2008-07-16T16:54:49.524Z</updated>
  </source>
</entry>

Creating a New Contact

A new contact is created by making an HTTP POST to the collection URI. The POST body must contain an Atom entry element that includes the content for the new contact. The Content-Type of the request must be set to application/atom+xml.

<entry xmlns="http://www.w3.org/2005/Atom">
  <title type="text"> </title>
  <updated>2008-07-23T14:21:06.407Z</updated>
  <author></author>
  <id>data:,none</id>
  <summary type="text">Contact</summary>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/">
      <EmailAddress>test101@example.com</EmailAddress>
      <FirstName>First</FirstName>
      <LastName>Last</LastName>
      <OptInSource>ACTION_BY_CONTACT</OptInSource>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1" />
      </ContactLists>
    </Contact>
  </content>
</entry>

Note that the id, title, author and updated elements must be present in the XML in order to conform to the Atom specification, even though their values will be replaced by the server. The title and author elements may be empty. The id must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness. The updated element must contain a date or date/time value, but again the value is not used by the server.

If the new Contact is created successfully, the server will return an HTTP status of 201 Created. The HTTP Location header in the response will contain the URI of the newly created Contact, and the entity body returned will be the entry for the Contact, including server-generated values like ids and links, with the result being that the returned response looks very much like what would be returned by a GET of the newly created contact's URI. Note that valid State Codes can be found here. State Code and Country must be consistent.

Updating a Contact

A Contact is updated by issuing an HTTP PUT to the entry's URI. The PUT body must contain an Atom entry element with the changed content for the contact.  The best way to achieve a successful update is to use the XML from a GET operation on the contact you want to update, modify the contents, and use it as the XML body in your PUT request.

Adding or Removing a Contact from a List

Contacts are added to or removed from lists by adding or removing ContactList elements from the ContactLists element, then PUT'ting the entry back to its edit URI. See below an example of the XML required to associate existing contact u86597@example.com with Contact Lists 1, 11, 12 and 14 in the joesflowersaccount. Note that after the PUT, contact u86597@example.com will be on ONLY Contact Lists 1, 11, 12 and 14 and will be removed from any other lists the contact was on previously.

<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/101</id>
  <title type="text">Contact: u86597@example.com</title>
  <updated>2008-04-25T19:29:06.096Z</updated>
  <author> </author>
  <content type="application/vnd.ctct+xml">
    <Contact xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/101">
      <EmailAddress>u86597@example.com</EmailAddress>
      <OptInSource>ACTION_BY_CUSTOMER</OptInSource>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/11"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/12"></ContactList>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/14"></ContactList>
      </ContactLists>
    </Contact>
  </content>
</entry>

Note that the OptInSource element is required, and must be ACTION_BY_CUSTOMER for any Contact List which is not included on the SignUp Form for the Account Owner.

Removing a Contact

To remove a contact from all lists, simply remove all of the ContactList elements from the ContactLists element.  Removing a contact does not mean that the contact has unsubscribed or opted out of receiving emails.  It means the contact simply does not belong to any particular contact list, and can be added back to a list by the account owner.  However, this API should not be used if the contact has unsubscribed from receiving all emails.  Instead, you should follow the instructions below in "Opting-out a Contact" section.

Opting-out a Contact

A Contact is opted-out by issuing an HTTP DELETE to the entry's URI. The call will return 204 No Content if it succeeds. This should be used if the contact has decided to unsubscribe from receiving all emails or has asked to stop sending all emails.  Opted-out Contacts become members of the do-not-mail special list.

Opting-in a Contact

Contacts who have opted out of receiving all mails and have been placed on Do-Not-Mail list must opt themselves in.  The account owner cannot add a contact in Do-Not-Mail list back to a different list.  When using the API, that means that the OptInSource must be ACTION_BY_CONTACT. Applications may only use the ACTION_BY_CONTACT OptInSource when the API call is the direct result of an action performed by the Contact (e.g. clicking a Subscribe button in an application). It is a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API in any other way.

Contact Data Format

ContactList Data Format

Managing Email Campaigns

Constant Contact provides API's that allow you to get details of email campaigns, to create an email campaign based on custom HTML code, and to update details of email campaigns.

You can get a list of campaigns, and query individual campaigns to get more details for each one.  If you want to create a new campaign, the best way is to get the details of a campaign, then make changes to the returned XML and use the modified XML to create a new one.

The following tasks are supported currently:

• Listing Campaigns
• Obtaining a Campaign's Information
• Creating a Campaign
  
• Updating a Campaign
  
• Searching for a Campaign
• Removing a Campaign

Listing Campaigns

You can get a list of campaigns avaialble in your account by using the GET method on the campaigns collection: 

https://api.constantcontact.com/ws/customers/{user-name}/campaigns

The GET on the campaigns collection returns a list of campaigns as described in the Campaigns Collection Reference.

Each campaign is returned in <entry> tags, and if there are multiple campaigns, there will be multiple <entry> elements.  Each entry provides only the basic information about a campaign, such as the name or title of the campaign, its author and status.  To get more details for a particular campaign, you need to  use the <link> provided inside <entry> to construct a new URI and query the campaign itself, and the resulting URI would look like the following:

https://api.constantcontact.com/ws/customers/{user-name}/campaigns/1100549626893

If you call the above URI with GET, you should be able to get more details about the campaign.  This action is described in more detail in Obtaining a Campaign's Information section.

Obtaining a Campaign's Information

You can obtain details of both template-based campaigns and custom-code campaigns.  For custom-code campaigns, you will get attributes of a campaign, such as subject, from email address, etc., as well as the actual content of the campaign, both HTML/XHTML and text.  For template-based campaigns, you will only get attributes of a campaign.

To obtain a campaign's information, call the following URI with GET method:

https://api.constantcontact.com/ws/customers/{user-name}/campaigns/{campaign-id}

The GET on the campaign resource returns the details of a campaign as described in the Campaigns Collection Reference.  The response body would return XML elements according to the Campaign Data Elements section of the Campaigns Collection Reference.  The details should include whether the campaign is based on templates or custom HTML/XHTML, whether the campaign is HTML or XHTML based if it's based on custom code, the campaign's status, details of the email itself, and settings on "View As Webpage" or "Permission Reminder" features.

<CampaignType> signifies whether the campaign is based on templates (STOCK) or on custom HTML/XHTML code (CUSTOM).  If the campaign is template-based, then the XML would not contain <EmailContent>, <TextContent> and <StyleSheet> elements.

If the campaign is based on custom code, then the returned elements depend on whether the campaign is HTML or XHTML based, described by <EmailContentFormat> element, whose valid values are HTML and XHTML.  If the custom campaign is based on HTML, then the XML would contain only <EmailContent> and <TextContent> elements.  If the custom campaign is based on XHTML, then the XML would contain <EmailContent>, <TextContent> and <StyleSheet>.

The email addresses used in <FromEmail> and <ReplyToEmail> are based on the email addresses of the account, which are represented through Account Settings Email Addresses collection and resource.  Please note that email addresses are represented as ID's and not actual email addresses.

The user's organization information is represented by <OrganizationName>, <OrganizationAddress1>, <OrganizationAddress2>, <OrganizationAddress3>, <OrganizationCity>, <OrganizationState>, <OrganizationInternationalState> and <OrganizationCountry> elements.  If you already entered organization information in your settings, or if you specified them when you created the campaign through the API, then these elements will return the organization information.  If they have not been set, they will not have any values.

Creating a Campaign

There are two types of email campaigns in Constant Contact: template-based emails that use email templates provided by Constant Contact and custom-code campaigns that use HTML/XHTML provided by the users, which is equivalent to using "Use My Own Code" option when creating a campaign in Constant Contact.

We only provide an ability to create a custom-code campaign through the API.  You can create either an HTML-based campaign or an XHTML-based campaign.  In both cases, you need to provide the details of the campaign you are trying to create, such as subject, from email address, reply-to email address, etc.

To create a campaign, call the following URI with POST method:

https://api.constantcontact.com/ws/customers/{user-name}/campaigns 

You also need to ensure that Content-Type HTTP header is set to application/atom+xml.  The body of the request should contain the elements of a campaign, as described in the Campaigns Collection Reference.  The following XML contains all the required elements to create a campaign and you just need to change the values to create a campaign.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/campaigns" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
  <title type="text">API Test Email</title>
  <updated>2009-10-19T18:34:53.105Z</updated>
  <author>
    <name>Constant Contact</name>
  </author>
  <content type="application/vnd.ctct+xml">
    <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/"
id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100546096289">
      <Name>API Test Email</Name>
      <Status>Draft</Status>
      <Date>2009-10-19T18:34:53.105Z</Date>
      <Subject>Enter email subject here</Subject>
      <FromName>joesflowers@example.com</FromName>
      <ViewAsWebpage>NO</ViewAsWebpage>
      <ViewAsWebpageLinkText></ViewAsWebpageLinkText>
      <ViewAsWebpageText></ViewAsWebpageText>
      <PermissionReminder>YES</PermissionReminder>
      <PermissionReminderText>You're receiving this email because of your relationship with ctct. 
Please &lt;ConfirmOptin>&lt;a style="color:#0000ff;">confirm&lt;/a>&lt;/ConfirmOptin> 
your continued interest in receiving email from us.</PermissionReminderText>
      <GreetingSalutation>Dear</GreetingSalutation>
      <GreetingName>FirstName</GreetingName>
      <GreetingString>Greetings!</GreetingString>
      <OrganizationName>ctct</OrganizationName>
      <OrganizationAddress1>123 wsw st</OrganizationAddress1>
      <OrganizationAddress2></OrganizationAddress2>
      <OrganizationAddress3></OrganizationAddress3>
      <OrganizationCity>Ashland</OrganizationCity>
      <OrganizationState>MA</OrganizationState>
      <OrganizationInternationalState></OrganizationInternationalState>
      <OrganizationCountry>us</OrganizationCountry>
      <OrganizationPostalCode>32423</OrganizationPostalCode>
      <IncludeForwardEmail>NO</IncludeForwardEmail>
      <ForwardEmailLinkText></ForwardEmailLinkText>
      <IncludeSubscribeLink>NO</IncludeSubscribeLink>
      <SubscribeLinkText></SubscribeLinkText>
      <EmailContentFormat>HTML</EmailContentFormat>
      <EmailContent>&lt;html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" 
xmlns:cctd="http://www.constantcontact.com/cctd">
&lt;body>&lt;CopyRight>Copyright (c) 1996-2009 Constant Contact. All rights reserved.  Except as permitted under a
separate
written agreement with Constant Contact, neither the Constant Contact software, nor any content that appears on any
Constant Contact site,
including but not limited to, web pages, newsletters, or templates may be reproduced, republished, repurposed, or
distributed without the
prior written permission of Constant Contact.  For inquiries regarding reproduction or distribution of any Constant
Contact material, please
contact joesflowers@example.com.&lt;/CopyRight>
&lt;OpenTracking/>
&lt;!--  Do NOT delete previous line if you want to get statistics on the number of opened emails -->
&lt;CustomBlock name="letter.intro" title="Personalization">
    &lt;Greeting/>
&lt;/CustomBlock>
&lt;/body>
&lt;/html></EmailContent>
      <EmailTextContent>&lt;Text>This is the text version.&lt;/Text></EmailTextContent>
      <StyleSheet></StyleSheet>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/lists/1" rel="self" />
        </ContactList>
      </ContactLists>
      <FromEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/settings/emailaddresses/1"
          rel="self" />
        </Email>
        <EmailAddress>joesflowers@example.com</EmailAddress>
      </FromEmail>
      <ReplyToEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/settings/emailaddresses/1"
          rel="self" />
        </Email>
        <EmailAddress>joesflowers@example.com</EmailAddress>
      </ReplyToEmail>
    </Campaign>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
    <title type="text">Campaigns for customer: joesflowers</title>
    <link href="campaigns" />
    <link href="campaigns" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-10-19T19:36:12.622Z</updated>
  </source>
</entry>

Because we use the Atom specification for XML, there are several elements that are required even though they are not used by the server and are replaced upon a successful contact creation.  These elements are <id>, <title>, <author>, and <updated> elements. The <title> and <author> elements may be empty. The <id> must contain a URI, but since the value is not used by the server, any URI will work. The server does not check for uniqueness when creating a contact because a new unique ID will be created anyway. The <updated> element must contain a date or date/time value, but again the value is not used by the server.

Since the API only supports creating a custom-code campaign, there is no reason to specify <CampaignType>, which will be ignored.

You need to ensure to specify the correct value in <EmailContentFormat> element.  If it is set to HTML, then the values in <EmailContent> will be treated like HTML the same was it is treated in our UI.  Since we do not validate the correctness of HTML, you will be able to create a HTML-based campaign with invalid HTML so it is imperative that you ensure your HTML is correct.

If it is set to XHTML, then the values in <EmailContent> will be treated like XHTML the same way it is treated in our UI, which means it will be subject to a more strict validation to ensure the XHTML is valid.  If it is not valid, you will receive an error and the campaign will not be created.  In addition, <TextContent> also needs to be in valid XHTML format and any text content you pass in must be enclosed by <Text></Text> tags.

<FromEmail> and <ReplyToEmail> must be set with the account's confirmed email addresses and their values must be valid ID's from Account Settings Email Addresses collection and resource.

There are three sets of elements that go together:

• <ViewAsWebpage>, <ViewAsWebpageLinkText> and <ViewAsWebpageText>
  If <ViewAsWebpage> is set to 'YES', then values in <ViewAsWebpageLinkText> and <ViewAsWebpageText> will be used, and a link to view the campaign as a webpage will be included in the campaign.  If <ViewAsWebpage> is set to 'NO', then values in the other two elements will be ignored. 
   
• <IncludeFowardEmail> and <ForwardEmailLinkText>
  If <IncludeFowardEmail> is set to 'YES', then the value in <ForwardEmailLinkText> will be used to insert a link in the campaign.  This is the same as "Forward Email to Friend" feature in the UI.  If <IncludeForwardEmail> is set to 'NO', then <FowardEmailLinkText> will be ignored.
   
• <IncludeSubscribeLink> and <SubscribeLinkText>
  If <IncludeSubscribeLink> is set to 'YES', then the value in <SubscribeLinkText> will be used to insert a link in the forwarded email for "Forward Email to Friend" feature in the UI.  If <IncludeSubscribeLink> is set to 'NO', then <SubscribeLinkText> will be ignored.

The elements <GreetingSalutation>, <GreetingName> and <GreetingString> ared used to specify how the greeting in the campaign should be set.  <GreetingSalutation> and <GreetingName> are combined to create a recipient-specific greeting; if the value specified in <GreetingName> does not exist for a particular contact, such as missing FirstName, then <GreetingString> will be used.  The valid values for <GreetingName> are 'FirstName', 'LastName', 'FirstAndLastName' or 'NONE'.

The user's organization information is represented by <OrganizationName>, <OrganizationAddress1>, <OrganizationAddress2>, <OrganizationAddress3>, <OrganizationCity>, <OrganizationState>, <OrganizationInternationalState> and <OrganizationCountry> elements.  You can specify values in these elements that will be applied speicfically to the campaign you are creating.  They do not overwrite the default settings for the user.

The actual content of the campaign is described by <EmailContent>, <TextContent> and <StyleSheet> elements.  For HTML campaign, you need to specify <EmailContent> and <TextContent>  For XHTML, you need to specify <EmailContent>, <TextContent> and optionally <StyleSheet>.  Any values passed through these elements, in both HTML and XHTML, must be HTML-encoded in order for the API to work properly.  For example, '<' must be converted to '&lt;', etc.  Most programming languages offer ways to perform HTML-encoding so you must utilize such functionality to do this.  If you are creating an XHTML campaign, invalid XHTML in <EmailContent> will give you an error and the campaign will not be created.

To learn more about how to use HTML and XHTML in your custom code campaign, please consult the Advanced Editor User Guide.

<PermissionReminder> and <PermissionReminderText> specify whether you want to include a link for a confirmed opt-in in your email.  Please note that because the text is part of an email, you must HTML-encode any tags you choose to use in <PermissionReminderText>, such as <ConfirmOptIn> tag.

For more details on the XML specification of the request body, please refer to the Campaign Collection and Resource Reference.

Updating a Campaign

You can update both template-based campaign and custom-code campaign.  For template-based campaign, you can only update properties associated with the campaign, but not the actual email content itself.  For custom-code campaign, you can update properties as well as update the HTML/XHTML associated with the campaign.  A campaign can only be updated in DRAFT status.

To update a campaign, the easiest way is to get details of a campaign, as described in Obtaining a Campaign's Information, and modify only the elements you would like to change, and use the resulting XML through a PUT operation on the campaign URI.

When updating a campaign, you can change values of elements that are marked as editable in the Campaign Collection Reference.

For a custom-code campaign, <EmailContent> is required.  If you have <EmailContent> in your request but do not have any values, then the content of the campaign will be deleted.  If <EmailContent> element is not included in the XML, then the HTML content of the campaign will not be touched.

To learn more about how to use HTML and XHTML in your custom code campaign, please consult the Advanced Editor User Guide.

The body of the request should contain the elements of a campaign, as described in the Campaigns Collection Reference.  Please note that values in non-editable elements do not matter when  you are creating a new campaign, but we advise you keep all the elements from a GET operation when you are creating a new campaign using the returned XML in order to make sure you can successfully create a campaign at all times.  Any editable elements that do not have any values specified during an update will overwrite any existing values with an empty field.  For example, if you had set <GreetingString> in your campaign, and then if you PUT <GreetingString></GreetingString>, then any value you had as your greeting string will be deleted.

Searching for a Campaign

You can search for campaigns based on their status.  In order to search for campaigns, use the campaigns collection and pass in the status as a parameter.  For example, to search for campaigns that have been sent, you can call GET on the following URI:

https://api.constantcontact.com/ws/customers/{user-name}/campaigns?status=SENT

The valid statuses are: DRAFT, RUNNING, SENT and SCHEDULED, and the case does not matter.

If there are no campaigns with the requested status, the API will return an empty feed with no <entry>.

Removing a Campaign

You can remove a campaign by issuing DELETE directly on a specific campaign.  This operation is the same as removing a campaign from the UI and will exclude the removed campaign from overall statistics.

For example, calling DELETE on the following URI will remove the campaign:

https://api.constantcontact.com/ws/customers/{user-name}/campaigns/{campaign-id}

Campaign Collection and Resource Reference

You can use campaigns collection list campaigns and create a new campaign, and use a specific campaign resource to modify or delete a campaign.  To find out more about how to use the campaign collection and resource, refer to Managing Email Campaigns.

The campaign resource utilizes another resource that represents the user's email addresses, in order to specify "From Eamil" and "Reply To Email" fields in a campaign.  To find out more about this resource, refer to Using Account Settings Email Addresses.  To read up on technical reference for the resource, refer to Account Settings Email Address Reference.

• Campaigns Collection
• Campaign Resource
• URI Format Specification
• Campaign Data XML Elements Specification

Campaigns Collection

The campaigns collection refers to a group of campaigns available to a particular user.  By performing GET on the collection itself, you retrieve a list of campaigns.  By performing a POST on the collection, you can add a new campaign to the collection.

Request Format

GET https://api.constantcontact.com/ws/customers/{user-name}/campaigns

For more detailed information about the URI, refer to the URI Format description.

For more information about listing campaigns, refer to Managing Email Campaigns.

Response Format

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
  <title type="text">Campaigns for customer: joesflowers</title>
  <link href="campaigns" />
  <link href="campaigns" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2009-10-19T18:55:01.918Z</updated>
  <link href="/ws/customers/joesflowers/campaigns?next=2" rel="next" />
  <link href="/ws/customers/joesflowers/campaigns" rel="current" />
  <link href="/ws/customers/joesflowers/campaigns" rel="first" />
  <entry>
    <link href="/ws/customers/joesflowers/campaigns/1100546096289" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100546096289</id>
    <title type="text">Spring Campaign</title>
    <updated>2009-10-19T18:34:53.105Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/campaigns/1100546096289">
        <Name>Spring Campaign</Name>
        <Status>Sent</Status>
        <Date>2009-10-19T18:34:53.105Z</Date>
      </Campaign>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/campaigns/1100546028219" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100546028219</id>
    <title type="text">Fall Campaign</title>
    <updated>2009-10-16T13:55:48.369Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/campaigns/1100546028219">
        <Name>Fall Campaign</Name>
        <Status>Draft</Status>
        <Date>2009-10-16T13:55:48.369Z</Date>
      </Campaign>
    </content>
  </entry>
</feed>

Each <entry> elements represent a campagin.  A campaign's unique ID is given by <id> and the link that you should use to retrieve the details of a campaign is given in <link> with rel attribute value of "edit".  You should use the value of this <link> element concatenated after our server name.  From the above example, the constructed URI for the campaign is https://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100546028219.

For more detailed descriptions of the XML elements, refer to the Campaign Elements Data section.

Request Format

POST https://api.constantcontact.com/ws/customers/{user-name}/campaigns

For more detailed information about the URI, refer to the URI Format description.

To learn more about how to create a campaign, please refer to the Managing Email Campaigns.

The XML body must be passed as part of the request to describe the campaign that you would like to create.  The following shows an example of what the XML should look like.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/campaigns" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
  <title type="text">API Test Email</title>
  <updated>2009-10-19T18:34:53.105Z</updated>
  <author>
    <name>Constant Contact</name>
  </author>
  <content type="application/vnd.ctct+xml">
    <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/"
id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100546096289">
      <Name>API Test Email</Name>
      <Status>Draft</Status>
      <Date>2009-10-19T18:34:53.105Z</Date>
      <Subject>Enter email subject here</Subject>
      <FromName>joesflowers@example.com</FromName>
      <ViewAsWebpage>NO</ViewAsWebpage>
      <ViewAsWebpageLinkText></ViewAsWebpageLinkText>
      <ViewAsWebpageText></ViewAsWebpageText>
      <PermissionReminder>YES</PermissionReminder>
      <PermissionReminderText>You're receiving this email because of your relationship with ctct. 
Please &lt;ConfirmOptin>&lt;a style="color:#0000ff;">confirm&lt;/a>&lt;/ConfirmOptin> 
your continued interest in receiving email from us.</PermissionReminderText>
      <GreetingSalutation>Dear</GreetingSalutation>
      <GreetingName>FirstName</GreetingName>
      <GreetingString>Greetings!</GreetingString>
      <OrganizationName>ctct</OrganizationName>
      <OrganizationAddress1>123 wsw st</OrganizationAddress1>
      <OrganizationAddress2></OrganizationAddress2>
      <OrganizationAddress3></OrganizationAddress3>
      <OrganizationCity>Ashland</OrganizationCity>
      <OrganizationState>MA</OrganizationState>
      <OrganizationInternationalState></OrganizationInternationalState>
      <OrganizationCountry>us</OrganizationCountry>
      <OrganizationPostalCode>32423</OrganizationPostalCode>
      <IncludeForwardEmail>NO</IncludeForwardEmail>
      <ForwardEmailLinkText></ForwardEmailLinkText>
      <IncludeSubscribeLink>NO</IncludeSubscribeLink>
      <SubscribeLinkText></SubscribeLinkText>
      <EmailContentFormat>HTML</EmailContentFormat>
      <EmailContent>&lt;html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" 
xmlns:cctd="http://www.constantcontact.com/cctd">
&lt;body>&lt;CopyRight>Copyright (c) 1996-2009 Constant Contact. All rights reserved.  Except as permitted under a
separate
written agreement with Constant Contact, neither the Constant Contact software, nor any content that appears on any
Constant Contact site,
including but not limited to, web pages, newsletters, or templates may be reproduced, republished, repurposed, or
distributed without the
prior written permission of Constant Contact.  For inquiries regarding reproduction or distribution of any Constant
Contact material, please
contact joesflowers@example.com.&lt;/CopyRight>
&lt;OpenTracking/>
&lt;!--  Do NOT delete previous line if you want to get statistics on the number of opened emails -->
&lt;CustomBlock name="letter.intro" title="Personalization">
    &lt;Greeting/>
&lt;/CustomBlock>
&lt;/body>
&lt;/html></EmailContent>
      <EmailTextContent>&lt;Text>This is the text version.&lt;/Text></EmailTextContent>
      <StyleSheet></StyleSheet>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/lists/1" rel="self" />
        </ContactList>
      </ContactLists>
      <FromEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/settings/emailaddresses/1"
          rel="self" />
        </Email>
        <EmailAddress>joesflowers@example.com</EmailAddress>
      </FromEmail>
      <ReplyToEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/settings/emailaddresses/1"
          rel="self" />
        </Email>
        <EmailAddress>joesflowers@example.com</EmailAddress>
      </ReplyToEmail>
    </Campaign>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
    <title type="text">Campaigns for customer: joesflowers</title>
    <link href="campaigns" />
    <link href="campaigns" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-10-19T19:36:12.622Z</updated>
  </source>
</entry>

For more detailed descriptions of the XML elements, refer to the Campaign Elements Data section.

Campaign Resource

The campaign resource refers to individual campaigns under the campaigns collection.  Each campaign is represented with an ID and resides under the campaigns collection in the URI.  By performing GET on a specific campaign resource, you retrieve details of a particular campaign.  By performing PUT on a specific campaign resource, you make updates to a particular campaign.   

Request Format

GET https://api.constantcontact.com/ws/customers/{user-name}/campaigns/{campaign-id}

For more detailed information about the URI, refer to the URI Format description.

To learn more about how to obtain a campaign's details, please refer to the Managing Email Campaigns.

Response Format

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/campaigns/1100545398420" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100545398420</id>
  <title type="text">joesflowers custom campaign HTML</title>
  <updated>2009-10-01T18:42:56.939Z</updated>
  <author>
    <name>Constant Contact</name>
  </author>
  <content type="application/vnd.ctct+xml">
    <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
    com/ws/customers/joesflowers/campaigns/1100545398420">
      <Name>joesflowers custom campaign HTML</Name>
      <Status>Draft</Status>
      <Date>2009-10-01T18:42:56.939Z</Date>
      <LastEditDate>2009-10-01T18:43:40.656Z</LastEditDate>
      <Sent>0</Sent>
      <Opens>0</Opens>
      <Clicks>0</Clicks>
      <Bounces>0</Bounces>
      <Forwards>0</Forwards>
      <OptOuts>0</OptOuts>
      <SpamReports>0</SpamReports>
      <Subject>Enter email subject here</Subject>
      <FromName>joesflowers</FromName>
      <CampaignType>CUSTOM</CampaignType>
      <ViewAsWebpage>YES</ViewAsWebpage>
      <ViewAsWebpageLinkText>Click here</ViewAsWebpageLinkText>
      <ViewAsWebpageText>Having trouble viewing this email?</ViewAsWebpageText>
      <PermissionReminder>YES</PermissionReminder>
      <PermissionReminderText>You're receiving this email because of your relationship with Constant Contact. Please &lt;
      ConfirmOptin>&lt;a style="color:#0000ff;">confirm&lt;/a>&lt;/ConfirmOptin> your continued interest in receiving
      email from us.</PermissionReminderText>
      <GreetingSalutation>Dear</GreetingSalutation>
      <GreetingName>First_Name</GreetingName>
      <GreetingString>Greetings!</GreetingString>
      <OrganizationName>Constant Contact</OrganizationName>
      <OrganizationAddress1>1601 Trapelo Rd.</OrganizationAddress1>
      <OrganizationAddress2></OrganizationAddress2>
      <OrganizationAddress3></OrganizationAddress3>
      <OrganizationCity>Waltham</OrganizationCity>
      <OrganizationState>MA</OrganizationState>
      <OrganizationInternationalState></OrganizationInternationalState>
      <OrganizationCountry>us</OrganizationCountry>
      <IncludeForwardEmail>YES</IncludeForwardEmail>
      <ForwardEmailLinkText>Forward email</ForwardEmailLinkText>
      <IncludeSubscribeLink>YES</IncludeSubscribeLink>
      <SubscribeLinkText>Subscribe me!</SubscribeLinkText>
      <EmailContentFormat>HTML</EmailContentFormat>
      <EmailContent>&lt;!-- If your HTML code DOES include the html, head, and body tags,
replace the entire code below with your custom HTML code.

Please note, if you want to use the Constant Contact personalized greeting,
make sure to add the &lt;Greeting/> tag to your code. -->

&lt;html>
&lt;body>
&lt;Greeting />
&lt;!-- If your HTML code DOES NOT include the html, head, and body tags,
paste your custom HTML code between the START and END comments  -->
&lt;!--    START    -->


&lt;!--     END     -->
&lt;/body>
&lt;/html></EmailContent>
      <EmailTextContent>&lt;Text>
&lt;Greeting />
&lt;/Text></EmailTextContent>
      <StyleSheet></StyleSheet>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/2">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.
          com/ws/customers/joesflowers/lists/2" rel="self" />
        </ContactList>
      </ContactLists>
      <FromEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.
          com/ws/customers/joesflowers/settings/emailaddresses/1" rel="self" />
        </Email>
        <EmailAddress>joesflowers@constantcontact.com</EmailAddress>
      </FromEmail>
      <ReplyToEmail>
        <Email id="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.
          com/ws/customers/joesflowers/settings/emailaddresses/1" rel="self" />
        </Email>
        <EmailAddress>joesflowers@constantcontact.com</EmailAddress>
      </ReplyToEmail>
    </Campaign>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
    <title type="text">Campaigns for customer: joesflowers</title>
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns" />
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-10-01T18:43:40.731Z</updated>
  </source>
</entry>

 For more detailed descriptions of the XML elements, refer to the Campaign Elements Data section.

Request Format

PUT https://api.constantcontact.com/ws/customers/{user-name}/campaigns/{campaign-id}

For more detailed information about the URI, refer to the URI Format description.

To learn more about how to modify a campaign, please refer to the Managing Email Campaigns.

The XML body used for PUT should look the same as the response you get from a GET operation.  The easiest way to make changes to a campaign is to retrieve its details through a GET operation, and modify only the elements you want and posting the changes using the PUT operation.

Request Format

DELETE https://api.constantcontact.com/ws/customers/{user-name}/campaigns/{campaign-id}

For more detailed information about the URI, refer to the URI Format description.

To learn more about how to delete a campaign, please refer to the Managing Email Campaigns.

URI Format

Campaign Data Elements

Retrieving Account Email Addresses

Each user has email addresses that have been registered in the user account.  These email addresses can be retrieved by using the Account Email Address resource.

Please select what you would like to do:

• Retrieving a List of Account Email Addresses
  
• Retrieving Email Address Details

Retrieving a List of Account Email Addresses

You can retrieve a list of account email addresses by using the GET method on the email address collection:

https://api.constantcontact.com/ws/customers/{user-name}/settings/emailaddresses

The GET method will return a list of email addresses that are registered in the account as described in the Account Email Address resource.  Each <entry> represents an email address, and its unique ID is presented in <id>.  The link that retrieves the details of an email address is presented in <link> with rel attribute of "edit".

Retrieving Email Address Details

You can get details of a particular email address by using the GET method on an email address resource:

https://api.constantcontact.com/ws/customers/{user-name}/settings/emailaddresses/{email-id}

The details of an email address include its status and verified time.

Account Email Addresses Collection and Resource

The account settings email address collection and resource allows you to retrieve a list of registered email addresses on your account as specified in the Settings in the UI. These email addresses are used in conjunction with campaign resource to specify From Email and Reply To email addresses.

To learn more about how to use email address collectino and resource, refer to Retrieving Account Email Addresses.

Account Email Addresses Collection

The email addresses collection gives you a list of email addresses you registered with your account in the Settings.  Each <entry> represents an email address and gives you a summary of each email address.

Request Format

GET https://api.constantcontact.com/ws/customers/{user-name}/settings/emailaddresses

For more detailed description about the above URI, please refer to the URI Format description.

To learn more about how to retrieve a list of email addresses registered in your account, please refer to Retrieving Account Email Addresses.

Response Format

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses</id>
  <title type="text" />
  <link href="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses" />
  <link href="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2009-10-01T20:18:22.775Z</updated>
  <entry>
    <link href="/ws/customers/joesflowers/settings/emailaddresses/1" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1</id>
    <title type="text">joesflowers@example.com</title>
    <updated>2009-05-21T17:44:04.609Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <Email xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/settings/emailaddresses/1">
        <EmailAddress>joesflowers@example.com</EmailAddress>
        <Status>Verified</Status>
        <VerifiedTime>2009-05-21T17:44:04.609Z</VerifiedTime>
      </Email>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/settings/emailaddresses/2" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/2</id>
    <title type="text">joesflowers2@example.com</title>
    <updated>2009-09-02T13:27:36.552Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <Email xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/settings/emailaddresses/2">
        <EmailAddress>joesflowers2@example.com</EmailAddress>
        <Status>Pending</Status>
      </Email>
    </content>
  </entry>
</feed>

Each <entry> represents an email address registered with the account.  Its unique ID is givein in <id> element while the link to get more of its detail is given in <link> element with rel attribute of "edit".

For more detailed descriptions of the XML elements, refer to the Email Address Elements Data section.

Account Email Address Resource

The account email address represents an email address that has been registered in your account.

Request Format

GET https://api.constantcontact.com/ws/customers/{user-name}/settings/emailaddresses/{email-id}

 For more detailed description about the above URI, please refer to the URI Format description.

To learn more about how to retrieve a list of email addresses registered in your account, please refer to Retrieving Account Email Addresses.

Response Format

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/settings/emailaddresses/1" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses/1</id>
  <title type="text">joesflowers@example.com</title>
  <updated>2009-05-21T17:44:04.609Z</updated>
  <author>
    <name>Constant Contact</name>
  </author>
  <content type="application/vnd.ctct+xml">
    <Email xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
    com/ws/customers/joesflowers/settings/emailaddresses/1">
      <EmailAddress>joesflowers@example.com</EmailAddress>
      <Status>Verified</Status>
      <VerifiedTime>2009-05-21T17:44:04.609Z</VerifiedTime>
    </Email>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses</id>
    <title type="text" />
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses" />
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/settings/emailaddresses" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-10-01T21:06:25.486Z</updated>
  </source>
</entry>

For more detailed descriptions of the XML elements, refer to the Email Address Elements Data section.

URI Format

Email Address Elements Data

Contact Events Service

Overview

The Contact Events service provides access to the events (email sends, opens, clicks...) associated with a Contact (within the past 90 days). It helps answer these kinds of question: What Campaigns (emails) did this Contact receive? Which emails did they open? What links did that Contact Click on? When did they perform that action?
The Contacts Events Services does this through several read-only collections that track the interactions between Campaigns and Contacts. The events include sends, opens, opt-outs (unsubscribes), clicks, bounces, and forwards. The contact events collections available can be determined by retrieving the service document from the URI http://api.constantcontact.com/ws/customers/{UserName}/contacts/{ContactId}/events/. (Note that the final '/' in the preceding URL is required.)

Example

Retrieving the service document for a contact in our sample, gets:

<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title type="text">Constant Contact Web Services Event Workspace</atom:title>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/bounces">
      <atom:title type="text">Bounce Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/clicks">
      <atom:title type="text">Click Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/forwards">
      <atom:title type="text">Forward Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/opens">
      <atom:title type="text">Open Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/optouts">
      <atom:title type="text">Opt-out Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/sends">
      <atom:title type="text">Send Events for Customer: joesflowers, Contact id: 2084</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
  </workspace>
</service>

The href attribute of each collection provides a link where that collection can be retrieved. Each collection will return a paged list of all the events of the type involving that contact for any campaign sent in the last 90 days. Events are immutable - once an event occurs, it never changes. Events are returned in reverse chronological order.

Here is an example of an event feed:

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/281/events/sends</id>
  <title type="text">Send Events for Customer: joesflowers, Contact id: 1</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-08-07T20:27:04.627Z</updated>
  <link href="/ws/customers/joesflowers/contacts/281/events/sends" rel="first" />
  <link href="/ws/customers/joesflowers/contacts/281/events/sends" rel="current" />
  <entry>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/281/events/sends/1122907878323,1,1217955004534</id>
    <title type="text">Email Send Event for Customer: joesflowers, Campaign: http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1122907878323</title>
    <updated>2008-08-05T16:50:04.534Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <SentEvent xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/281/events/sends/1122907878323,1,1217955004534">
        <Contact id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1">
          <EmailAddress>ianjones@example.net</EmailAddress>
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1" rel="self" />
        </Contact>
        <Campaign id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1122907878323">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1122907878323" rel="self" />
        </Campaign>
        <EventTime>2008-08-05T16:50:04.534Z</EventTime>
      </SentEvent>
    </content>
  </entry>
</feed>

All events have the same basic form: a reference to a Contact, a reference to a Campaign, and the time when the event occurred. Some event types include additional information, see the data format description below.

Contact Tracking Event Data Format

All contact events have the following elements:

Bounce Event Data Format

In addition to the Contact Tracking Event elements described above, Bounce events have the following additional elements:

Click Event Data Format

In addition to the Contact Tracking Event elements described above, Click events have the following additional elements:

Forward Event Data Format

Forward events have no additional elements beyond the Contact Tracking Event elements described above.

Open Event Data Format

Open events have no additional elements beyond the Contact Tracking Event elements described above.

Optout Event Data Format

In addition to the Contact Tracking Event elements described above, Optout events have the following additional elements:

Send Event Data Format

Send events have no additional elements beyond the Contact Tracking Event elements described above.

Sample Usage

See this page for a code example.

Campaign Events resource

Overview

The Campaign Events service provides access to the detailed results (Open, Click, Bounce and other Events) associated with any Campaign (email) sent in the last 90 days. It helps answer these kinds of question: What Contacts Opened my last email? What links in the Campaign did they Click On? When did the Contact perform the action?

The Campaign Events service does this through several read-only collections that track the interactions between Campaigns and Contacts. The events include sends, opens, opt-outs (unsubscribes), clicks, bounces, and forwards. The campaign events collections available can be determined by retrieving the service document from the URI http://api.constantcontact.com/ws/customers/{UserName}/campaigns/{CampaignID}/events/. (Note that the final '/' in the preceding URL is required).
 

Example

Retrieving the service document for a campaign in our sample, http://api.constantcontact.com/ws/customers/{UserName}/campaigns/{CampaignID}/events/, returns this XML:

<?xml version='1.0' encoding='UTF-8'?>
<service xmlns="http://www.w3.org/2007/app" xmlns:atom="http://www.w3.org/2005/Atom">
  <workspace>
    <atom:title type="text">Constant Contact Web Services Event Workspace</atom:title>
    <collection href="/ws/customers/joesflowers/campaigns/1100544815515/events/bounces">
      <atom:title type="text">Bounce Events for Customer: joesflowers, Campaign id: : 1100544815515</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/campaigns/1100544815515/events/forwards">
      <atom:title type="text">Forward Events for Customer: joesflowers, Campaign id: : 1100544815515</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/campaigns/1100544815515/events/opens">
      <atom:title type="text">Open Events for Customer: joesflowers, Campaign id: : 1100544815515</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/campaigns/1100544815515/events/optouts">
      <atom:title type="text">Opt-out Events for Customer: joesflowers, Campaign id: : 1100544815515</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
    <collection href="/ws/customers/joesflowers/campaigns/1100544815515/events/sends">
      <atom:title type="text">Send Events for Customer: joesflowers, Campaign id: : 1100544815515</atom:title>
      <accept>application/atom+xml; type=entry</accept>
    </collection>
  </workspace>
</service>

The href attribute of each collection provides a link where a collection of the events of that type (Opens, Clicks...) can be retrieved. Each collection will return a paged list of all the Events of the type for that Campaign. Detailed Campaign Events are maintained for a period of 90 days following the first send of that Campaign. Events are immutable. Once an Event occurs, it never changes. Events are returned in reverse chronological order.

The Campaign resource has also been modified slightly. A URLs collection has been added that includes any URLs from email campaigns that have registered click events. See below for an example:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <link href="/ws/customers/joesflowers/campaigns/1102414826616" rel="edit" />
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1102414826616</id>
  <title type="text">Copy of Jen R5 Deployment</title>
  <updated>2009-01-18T14:00:04.681Z</updated>
  <author>
    <name>Constant Contact</name>
  </author>
  <content type="application/vnd.ctct+xml">
    <Campaign xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1102414826616">
      <Name>Copy of Jen R5 Deployment</Name>
      <Status>Sent</Status>
      <Date>2009-01-18T14:00:04.681Z</Date>
      <LastEditDate>2009-01-17T13:53:12.932Z</LastEditDate>
      <LastRunDate>2009-01-18T14:00:04.676Z</LastRunDate>
      <Sent>1</Sent>
      <Opens>1</Opens>
      <Clicks>1</Clicks>
      <Bounces>0</Bounces>
      <Forwards>0</Forwards>
      <OptOuts>0</OptOuts>
      <SpamReports>0</SpamReports>
      <Urls>
        <Url id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1102414826616/events/urls/1011301655704/clicks">
          <value>http://www.bestbuy.com</value>
          <Clicks>1</Clicks>
        </Url>
      </Urls>
      <ContactLists>
        <ContactList id="http://api.constantcontact.com/ws/customers/joesflowers/lists/41">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/lists/41" rel="self" />
        </ContactList>
      </ContactLists>
    </Campaign>
  </content>
  <source>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns</id>
    <title type="text">Campaigns for customer: joesflowers</title>
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns" />
    <link href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns" rel="self" />
    <author>
      <name>joesflowers</name>
    </author>
    <updated>2009-01-19T13:47:03.700Z</updated>
  </source>
</entry>

Here is an example of an Event feed:

<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100544815515/events/sends</id>
  <title type="text">Send Events for Customer: joesflowers, Campaign id: 1100544815515</title>
  <link href="" />
  <link href="" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2008-08-07T20:27:04.627Z</updated>
  <link href="/ws/customers/joesflowers/campaigns/1100544815515/events/sends" rel="first" />
  <link href="/ws/customers/joesflowers/campaigns/1100544815515/events/sends" rel="current" />
  <entry>
    <id>http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100544653344/events/sends/1122907878323,1,1217955004534</id>
    <title type="text">Email Send Event for Customer: joesflowers, Campaign: http://api.constantcontact.com/ws/customers/joesflowers/campaigns/110054...
    <updated>2008-08-05T16:50:04.534Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <SentEvent xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100544815515/events/sends/1100544815515,1,1217692805901">
        <Contact id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1">
          <EmailAddress>ianjones@example.net</EmailAddress>
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/contacts/1" rel="self" />
        </Contact>
        <Campaign id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1122907878323">
          <link xmlns="http://www.w3.org/2005/Atom" href="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100544815515" rel="self" />
        </Campaign>
        <EventTime>2008-08-05T16:50:04.534Z</EventTime>
      </SentEvent>
    </content>
  </entry>
</feed>

All events have the same basic form: a reference to a Contact, a reference to a Campaign, and the time when the event occurred. NOTE: Event detail information is only available for campaigns that were first sent in the past 90 days. Detail data for campaigns older than 90 days is not available, but high level aggregate statistics (number of sent, opens, etc) are available.

Some event types include additional information, see the data format description below.

Contact Tracking Event Data Format

All contact events have the following elements:

Bounce Event Data Format

In addition to the Contact Tracking Event elements described above, Bounce events have the following additional elements:

Forward Event Data Format

Forward events have no additional elements beyond the Contact Tracking Event elements described above.

Open Event Data Format

Open events have no additional elements beyond the Contact Tracking Event elements described above.

Optout Event Data Format

In addition to the Contact Tracking Event elements described above, Optout events have the following additional elements:

Send Event Data Format

Send events have no additional elements beyond the Contact Tracking Event elements described above.

REST API Authentication - Overview

API Authentication Overview

While the Constant Contact REST APIs technically supports several authentication models, at this point developers should leverage our Basic Authentication model.
 

Basic Authentication Over HTTPs

The Basic Authentication model should be used for all new development projects.

OAuth Authentication (Support Retracted)

Constant Contact developed and deployed support for an OAuth based Authentication model. However, due to a recently announced and acknowledged security vulnerability with the protocol, we are retracting support for our OAuth model. We are investigating the issue and considering appropriate API adjustments. Developers can and should leverage Basic Authentication. (For more information on the OAuth based vulnerability, please see this reference on the OAuth site).

Digest Authentication (Support Withdrawn July 31st 2009)

Constant Contact has deprecated support for the use of Digest Authentication with the REST APIs. Applications which are already using Digest Authentication will need to migrate their applications to another Authentication model by August 2009. Existing applications are encouraged to migrate to the OAuth based authentication model.

       define("URI", "http://api.constantcontact.com");
       $request_token_url  = URI.'/ws/oauth_get_request_token';
       $parsed = parse_url($request_token_url );
       $params = array();

       $req_req = OAuthRequest::from_consumer_and_token($oauth _consumer, NULL, "GET", $request_token_url, $params);
       $oauth_consumer = new OAuthConsumer($consumer_key, $consumer_secret, NULL);
       $sig_method = new OAuthSignatureMethod_HMAC_SHA1();
       $req_req->sign_request($sig_method, $oauth_consumer, NULL);

 
       $request  = $req_req->to_url();
       $session = curl_init($request);
       curl_setopt($session, CURLOPT_RETURNTRANSFER, 1);
       // Make the request
       $response = curl_exec($session);

       //Error Handling:
       // there is an error while executing the request, 
       if (!$response) {  
            $response = curl_error($curl);  
        }  
       curl_close($session);

       parse_str($response, $params);
       $oauth_token = $params['oauth_token'];
       $oauth_token_secret = $params['oauth_token_secret'];
       $_SESSION[CONSUMER_KEY] = $consumer_key;
       $_SESSION[CONSUMER_SECRET] = $consumer_secret;
       $_SESSION[REQUEST_TOKEN] = $oauth_token;
       $_SESSION[REQUEST_TOKEN_SECRET] = $oauth_token_secret;

       //initialize $context_root variable with application’s root.
       $callback_url = $context_root . "access_token.php";
       $auth_url = URI.'/ws/oauth_authorize_token?oauth_token='.$oauth_token.'&oauth_callback='.urlencode($callback_url);
       Header("Location: $auth_url");

       $request_token = $_SESSION[REQUEST_TOKEN];
       $request_token_secret = $_SESSION[REQUEST_TOKEN_SECRET];
       $consumer_key = $_SESSION[CONSUMER_KEY];
       $consumer_secret = $_SESSION[CONSUMER_SECRET];
       $access_url = URI.'/ws/oauth_get_access_token';

       $sig_method = new OAuthSignatureMethod_HMAC_SHA1();
       $access_consumer = new OAuthConsumer($consumer_key, $consumer_secret, NULL);
       $access _token = new OAuthConsumer($request_token, $request_token_secret);
       $parsed = parse_url($access_url);
       $params = array();
       $acc_req = OAuthRequest::from_consumer_and_token($test_consumer, $test_token, "GET", $endpoint, $params);
       $acc_req->sign_request($sig_method, $test_consumer, $test_token);

       $request  = $acc_req->to_url();
       $session = curl_init($request);
       curl_setopt($session, CURLOPT_RETURNTRANSFER, 1);
       // Make the request
       $response = curl_exec($session);
       //Error Handling:
       // there is an error while executing the request, 
       if (!$response) {  
            $response = curl_error($curl);  
        }  
       curl_close($session);

       parse_str($response, $params);
       $access_token = $params['oauth_token'];
       $access_token_secret = $params['oauth_token_secret'];
       $_SESSION[ACCESS_TOKEN] = $access_token;
       $_SESSION[ACCESS_TOKEN_SECRET] = $access_token_secret;

       $consumer = new OAuthConsumer($_SESSION[CONSUMER_KEY], $_SESSION[CONSUMER_SECRET], NULL);
       $token = new OAuthToken($_SESSION[ACCESS_TOKEN], $_SESSION[ACCESS_TOKEN_SECRET]);
       $parsed = parse_url($webServiceUrl);
       $params = array();
       parse_str($postVars, $params);
       $request = OAuthRequest::from_consumer_and_token($consumer, $token, $method, $webServiceUrl, $params);
       $request->sign_request(new OAuthSignatureMethod_HMAC_SHA1(), $consumer, $token);
	

       $response = send_request($request->get_normalized_http_method(), 
       	$webServiceUrl, $request, null);
       // Get the XML from the response, bypassing the header
       //Error Handling:
       //if there is an error, response will have error code and 
       //corresponding error message
       if (!($xml = strstr($response, '<?xml'))) {
       	 echo $response;
       	 $xml = null;
       }	

      
       <?php
       if (isset($xml)){
       	$data = simplexml_load_string($xml);
       	foreach ($data->entry AS $item){
       		$shortId = substr($item->id, 
       			strrpos($item->id, "/") + 1)
       ?>
       <input type='checkbox' name='lists[]' 
       	value='<?php echo $item->id ?>'>
       
       <a href='showList.php?listId='>
       <?php echo $item->content->ContactList->Name ?>
       
       <?php
       } ?>

Site Visitor API

Overview

Support and Questions on the SiteVisitor API

                var httpService:HTTPService = new HTTPService();
                var url:String = "proxy.php?ea="+emailText.text;
                httpService.url = url;
                httpService.showBusyCursor=true;
                httpService.send();

ListManager API

The ListManager API is a limited availability API which was designed to support bulk upload of contacts.

The ListManager API has been fully subsumed by the REST API effort. If you are already using this API, you may continue to do so for the time being.

We encourage all ListManager API users to consider the expanded functionality and improved access control provided in the newer Constant Contact REST APIs covered here .

Partner / Site Owner Management APIs

Site Owner API

Overview

The SiteOwner API is designed to help partners automate the process of creating and managing Constant Contact Accounts.
The SiteOwner API allows a partner to:

• Provision a site owner
• Update a site owner
• Retrieve a site owner’s Constant Contact site owner ID.
• Deactivate a site owner
• Reactivate a site owner
• Autologin the site owner - Allow a site owner to log on to Constant Contact from the hosting provider’s application or Web site
• Obtain all of a site owner’s tags (Constant Contact sign-up prompts) for automatic inclusion on the site owner’s Web site
• Obtain a single site owner’s tag for automatic inclusion on the site owner’s Web site
• Retrieve specific information about a Site Owner

Access to the SiteOwner API is a restricted access API provided to some Constant Contact Business Partners depending on the specific needs of the partner and the appropriateness of the API for those needs. The SiteOwner API operations can be applied only to accounts which are within the Business Partner's privilege hierarchy (generally, this means accounts which signed up through the Business Partner).

Accessing the SiteOwner API

If your integration needs include provisioning and managing Constant Contact accounts for your customers, please send a request, including your contact information, to the web services team.

Partner API

Overview

The SiteOwner API is designed to Enable a partner to provision and manage sub-partners. Access to the Partner API is applicable only to specific Constant Contact Business Partners who have been provided the privileges to establish and manage sub-partners. To request access to the Partner API, please contact the webservices team. Please include your business partner name and contact details.