Campaign Events Resource

webservices · ‎03-25-2011

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

https://api.constantcontact.com/ws/customers/{UserName}/campaigns/{CampaignID}/events/

(Note that the final '/' in the preceding URL is required).

Overview Managing Pagination of Campaign Events

Campaign events, like most other resources, are returned in pages. The Campaign Events service supports an optional parameter, pageSize, which is used to define the maximum number of events to be returned in each page of results. For example, to request that the open results for a specific campaign be returned in groups of 200, you can GET the following URI:

https://api.constantcontact.com/ws/customers/{UserName}/campaigns/{CampaignID}/events/

The pageSize parameter would typically be used to increase the number of events returned with each request, thus reducing the total number of required requests. The currently supported values for are 1 <= pageSize <=200. If no value is provided, the default value (50) will be used.

Example

Retrieving the service document for a campaign in our sample, xxxxxx

https://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/10113016...">
          <value>< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">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>< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">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>< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">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>< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">< a style="text-decoration: none;" onclick="return false" onmouseover="return false" rel="nofollow" target="_blank" onfocus="return false">http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100544653344/events/sends/1122907...</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/1100544...">
        <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:

Name	Allowed values	Description
Contact		A reference to the Contact involved in the event. Contents of this element include an EmailAddress element and an `atom:link` element with its `href` attribute linking to the Contact.
Campaign		A reference to the Campaign which triggered the event. Contents of this element include an `atom:link` element with its `href` attribute linking to the Campaign.
EventTime	Date/Time	The time the event occurred, in Atom Date format.

Bounce Event Data Format

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

Name	Allowed values	Description
Code	B, D, F, S, V, X or Z	One-letter bounce code.
Description		Description of the Code value: B: Non-existent address D: Undeliverable F: Mailbox Full S: Suspended V: Vacation/Auto Reply X: Other Z: Blocked
BounceMessage		Any message associated with the bounce.

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:

Name	Allowed values	Description
OptOutSource	ACTION_BY_CUSTOMER, ACTION_BY_CONTACT	Source of the opt-out
OptOutReason	Text	If provided, reason for the opt-out

Send Event Data Format

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