Campaign resource and endpoints overview.

Create email campaigns to engage, communicate, and interact with your existing contacts, and to enroll new contacts.

Campaign Resource

The email campaign resource serves as the foundation from which you build and manage your campaigns.

The table that follows lists and describes the email campaign resource properties.

PropertyTypeDescription
campaign_activitiesarrayIdentifies campaign activity details. The id uniquely identifies each campaign level activity (UUID format). The role, type parameters provide details about the activity. PRIMARY_EMAIL is the primary activity type ("primary_email", "email"). PERMALINK is the activity used for sharing campaign links ("permalink", "permalink"). RESEND_NON_OPENERS_EMAIL is the activity used to resend email to non-openers ("email", "resend").
campaign_id stringThe Universally Unique Identifier (UUID) that identifies the email campaign. The UUID format (8-4-4-4-12) includes a total of 36 characters, 32 alphanumeric characters, and four hyphens. The UUID is read-only. For example: 8987dc1a-48ef-433a-b836-7ca4f9aa3481.
created_atstring The system generated date and time that the email campaign was created. The read-only date and time displays in ISO-8601 format. For example: 018-02-06T22:09:15.000Z.
current_status stringDisplays the current campaign status. Draft status indicates that the email campaign is not complete or ready to be sent to contacts. The campaign lifecycle after it is first initialized (created) generally flows as follows: Draft (an email campaign can only be modified when the status is Draft and before it is sent or scheduled to be sent to contacts), Scheduled (the date to send the email campaign to contacts), Executing (brief status while in the process of sending), Done (campaign is no longer Active and has been sent), Removed (campaign was removed from the user's account and is no longer available, but is viewable from the Removed folder), Error (the system has detected an error)."
namestringThe descriptive name given to identify the email campaign. For example: "April News Letter for Dog Lovers". Email campaign names must be unique. You can choose to rename a email campaign.
typestringThe email campaign type is read-only and derived from the campaign template that you select when creating the email campaign. Available types include: Newsletter and Custom Code Email.
updated_atstringThe system generated date and time showing when the email campaign was last updated. When using the GET campaigns method and endpoint, include updated_at as a query parameter to limit the number of email campaigns returned. This query is also helpful when you need to sync email campaigns across accounts. This is a read-only value and is in ISO-8601 format. For example: 018-02-06T22:09:15.000Z.

Email Campaign Endpoints and Methods

Use the following endpoints and methods to create, update, and retrieve details about your email campaigns.

GET a Collection of V2 and V3 API Email Campaign Identifiers

GET /emails/campaign_id_xrefs

Use this method to migrate your local V2 API email data to the V3 API format. For each v2_email_campaign_id value that you provide, this method returns the corresponding V3 campaign_id and V3 campaign_activity_id UUID value.

Learn More about migrating your V2 API email data.

Try it!

POST (Create) a New Email Campaign

POST /emails

Use this method to create a new email campaign in your email collection by specifying a unique name for the email campaign and all required email_campaign_activities properties in the request body parameter.

When you create a new email campaign using the V3 API, the system automatically generates the following metadata for each new email campaign:

  • campaign_id: The ID (in UUID format) that uniquely identifies the email campaign.
  • current_status: The current status of the email campaign (set to DRAFT when first created).
  • created_at: The date and time that the email campaign is created.
  • updated_at: The date and time that the email campaign either created or was last updated.
  • campaign_activities: Identifies the role (purpose) of each campaign activity within the email campaign, and the campaign_activity_id that is used to uniquely identify each campaign activity.
    • primary_email: The primary marketing campaign email to use and send to contacts.
    • permalink: The system-generated permanent link to a web accessible version of the email campaign content. The content does not include any personalized email information, such as contact email addresses.

Learn more about creating new email campaigns.

Try it!

GET a Collection of Email Campaigns

GET /emails

Use this method to get a list (collection) of all existing email campaigns for your user account. If no campaigns exist for your account, the 200 response returns an empty list. To get details about a specific campaign, use the GET /emails/{campaign_id} method.

Use the following parameter to limit the number of campaigns to display on a single output page:

  • limit: Specify the number of campaigns, from 1-500, to display per page of output.

Learn more about getting details about your collection of email campaigns.

Try it!

GET Email Campaign Details by Campaign ID

GET /emails/{campaign_id}

Use this method to get details about a specific email campaign; including a list of campaign activity IDs. To get details about a specific campaign activity, use the GET /emails/activities/{campaign_activity_id}

Learn more about getting email campaign activity by campaign_id.

Try it!

GET Email Campaign Activity by Activity ID

GET /emails/activities/{campaign_activity_id}

Use this method to get a specific email campaign activity using the campaign_activity_id.

You can choose to include the following properties and subresources in the response (accepts a comma separated list):

  • permalink_url
  • html_content
  • document_properties
  • physical_address_in_footer

Learn more about how to get a specific email campaign activity and the type of email information returned in the API response.

Try it!

PUT (update) an Email Campaign Activity

PUT /emails/activities/{campaign_activity_id}

Use this method to update a specific email campaign activity using the campaign_activity_id. Updating an email campaign activity allows you to change the content of an campaign activity when it is in Draft status. You can also use this method to add contacts to a campaign activity using either contact lists or segments.

Learn more about how to update a specific email campaign activity.

Try it!

PATCH (rename) an Existing Email Campaign

PATCH /emails/{campaign_id}/

Use this method to rename an existing campaign.

Learn more about renaming an existing email campaign.

Try it!

GET Send History Details for Email Campaign Activities

GET /emails/activities/{campaign_activity_id}/send_history

Use this method to get email campaign history details, such as the email ID and send status.

Learn more

Try it!

POST Schedule an Email Campaign Activity

POST /emails/activities/{campaign_activity_id}/schedules

Use this method to schedule an email campaign activity.

Learn more about scheduling email campaign activities.

Try it!

GET Schedule Information for an Email Campaign Activity

GET /emails/activities/{campaign_activity_id}/schedules

Use this method to return the schedule information for an email campaign activity. This schedule information includes the date that Constant Contact will send the email to the contact lists or segment in the email campaign activity.

Learn more about returning the schedule information for an email campaign activity.

Try it!