Home › Constant Contact Web Service APIs › REST API Reference

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

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}