Our v3 API is now available! Learn more by visiting the v3 developer portal. Creating new v2 API keys is no longer supported.

Using the Email Campaign Endpoints

The email campaign endpoints are used to create, schedule, and manage Constant Contact email marketing campaigns. Here is a collection best practices, and tips & tricks to help you fully leverage this set of functionality.

Creating an email campaign

There are several components and parameters to an email campaign, some of which are not required. 

HOW Make POST call to the Email Campaigns API to create a new email campaign.

Required properties

You do not have to include all available properties when creating a new email campaign, only the following REQUIRED properties:

  • subject
  • from_name
  • from_email - from_email must be a verified email associated with the account.
  • name
  • text_content*
  • email_content*

*See UI vs. API created campaigns for TEMPLATE_V2 template type exceptions.

Optionally required properties - wait, what?

The following properties are by default optional, but become required once another property is set to true, or under other conditions.

Property Is required when...
message_footer ___ The fields in the message_footer array are required if the account owner has not set the organization address in their account information
view_as_web_page_link_text ___ REQUIRED if is_view_as_webpage_enabled = true
view_as_web_page_text ___ REQUIRED if is_view_as_webpage_enabled = true
permission_reminder_text ___ REQUIRED if is_permission_reminder_enabled = true

UI vs. API created campaigns

Currently the API behaves differently depending on which template_type a campaign is using. How a campaign is created determines the template type. Campaigns created using the API use the CUSTOM template_type; campaigns created using the UI can use any template_type. The following table characterizes differences in API behavior based on a campaign's template_type.

template_type scer Where created scer API behavior
CUSTOM API No limitations, all fields are available for modification (except normal read-only fields)
STOCK UI - standard campaign editor

Campaign text and HTML content cannot be edited using the API. The following fields are not exposed in the API: 

  • text_content
  • email_content
TEMPLATE_V2 UI - V2 Campaign Editor

Campaign text and HTML content cannot be edited using the API. The following fields are not exposed in the API:

  • email_content
  • email_content_format
  • style_sheet
  • subscribe_link_text
  • text_content

The following fields are not meaningful in this template, and return null values unless otherwise noted: 

  • greeting_name - returns "NONE"
  • greeting_salutations
  • greeting_string
  • is_permission_reminder_enabled - returns "false"
  • is_view_as_webpage_enabled - returns "false"
  • permission_reminder_text<
  • view_as_web_page_link_text
  • view_as_web_page_text
  • include_forward_email - returns "false"
  • include_subscribe_link - returns "false"

Updating an email campaign

HOW Make a PUT call to the Individual Email Campaign API to update an existing email campaign. Only campaigns in a DRAFT status can be updated. 

BEST PRACTICE Make a GET call to retrieve all the properties for a campaign prior to updating it. All updates (PUTs) are full replacements of the campaign properties. That means you need to include the original content that is not changing, plus the new and changed content in the PUT. Otherwise, all existing properties not specified in the PUT will be overwritten with a null set.

Deleted Campaigns

Details of a deleted campaign cannot be retrieved. If a call is made to GET a deleted campaign by its ID, the call will fail and return a 404 Not Found response. You can login to the account to restore the campaign and then retrieve its details.