Contact Events Service

[webservices]

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 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.  In addition, the Contact Events include a summary that lists all reporting data for each campaign.

To get the list of available events, you can call the GET method on the following URI:

https://api.constantcontact.com/ws/customers/{user-name}/contacts/{contact-id}/events/

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

In addition to the collections that represent the individual events, the Contact Events service provides a summary collection, which lists the number of events for each campaign.

Contact Events Service

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>
    <collection href="/ws/customers/joesflowers/contacts/2084/events/summary">
      <atom:title type="text">Events Summary 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.

Contact Event Resource

Here's an example of what an event resource looks like.

<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 Event Summary Collection

The summary collection provides a convenient way to see the event data for a contact organized by campaigns instead of a large flat list.  Here's an example of what the collection looks like:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://api.constantcontact.com/ws/customers/joesflowers/contacts/53/events/summary </id>
  <title type="text">Events Summary for Customer: joesflowers, Contact id: 53</title>
  <link href="summary" />
  <link href="summary" rel="self" />
  <author>
    <name>joesflowers</name>
  </author>
  <updated>2010-01-13T18:09:48.205Z</updated>
  <entry>
    <link href="/ws/customers/joesflowers/contacts/53/events/summary/1100552708599" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/events/summary/1100552708599</id>
    <title type="text">Events Summary for Customer: joesflowers, Contact id: http://api.constantcontact.
    com/ws/customers/joesflowers/contacts/53</title>
    <updated>2010-01-13T18:09:49.744Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <ReportsSummary xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/events/summary/1100552708599">
        <Contact id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/53">
          <EmailAddress>customer1@example.com</EmailAddress>
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/contacts/53" rel="self" />
        </Contact>
        <Campaign id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100552708599">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/campaigns/1100552708599" rel="self"
          />
          <Name>Jan 08 2010</Name>
        </Campaign>
        <Opens>2</Opens>
        <Clicks>1</Clicks>
        <Forwards>0</Forwards>
      </ReportsSummary>
    </content>
  </entry>
  <entry>
    <link href="/ws/customers/joesflowers/contacts/53/events/summary/1100552526522" rel="edit" />
    <id>http://api.constantcontact.com/ws/customers/joesflowers/events/summary/1100552526522</id>
    <title type="text">Events Summary for Customer: joesflowers, Contact id: http://api.constantcontact.
    com/ws/customers/joesflowers/contacts/53</title>
    <updated>2010-01-13T18:09:49.749Z</updated>
    <author>
      <name>Constant Contact</name>
    </author>
    <content type="application/vnd.ctct+xml">
      <ReportsSummary xmlns="http://ws.constantcontact.com/ns/1.0/" id="http://api.constantcontact.
      com/ws/customers/joesflowers/events/summary/1100552526522">
        <Contact id="http://api.constantcontact.com/ws/customers/joesflowers/contacts/53">
          <EmailAddress>customer1@example.com</EmailAddress>
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/contacts/53" rel="self" />
        </Contact>
        <Campaign id="http://api.constantcontact.com/ws/customers/joesflowers/campaigns/1100552526522">
          <link xmlns="http://www.w3.org/2005/Atom" href="/ws/customers/joesflowers/campaigns/1100552526522" rel="self"
          />
          <Name>Jan 04 2010</Name>
        </Campaign>
        <Opens>1</Opens>
        <Clicks>0</Clicks>
        <Forwards>0</Forwards>
      </ReportsSummary>
    </content>
  </entry>
</feed>

Each entry reprents a summary report for a campaign that has been sent to this particular contact.  For each campaign, you can see its name as well as its link that allows you to get even more campaign details if you woud like.  At the moment, for each contact, we only report opens, clicks and forwards.  For a camapign, if you access the campaign resource's events, you will see more data across all contacts who received that particular email.

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.

Click Event Data Format

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

Name	Allowed values	Description
LinkUrl	URL	The link that was clicked.

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 aboce.

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.

Sample Usage

See this page for a code example.