What are Email Campaigns?

Email campaigns allow you to engage with your contacts through email marketing. Sending email campaigns to your contacts can help grow your audience and build your brand.

In the V3 API, you manage emails using email campaigns and email campaign activities.

  • Email campaigns are a broad email marketing effort that may include multiple emails. Each email campaign contains a unique name and has a list of associated email campaign activities.
Example email campaign schema
{
    "type": "NEWSLETTER",
    "name": "Holiday Newsletter",
    "campaign_id": "f5ea685c-5fc8-47ab-9576-dbc21fea8198",
    "current_status": "SCHEDULED",
    "updated_at": "2019-10-25T17:20:39.000Z",
    "created_at": "2019-09-11T17:21:21.000Z",
    "campaign_activities": [
        {
            "role": "primary_email",
            "campaign_activity_id": "4a07b9b5-c69e-4079-855e-8c4959c18885"
        },
        {
            "role": "resend",
            "campaign_activity_id": "fff33557-a792-4a36-b0f5-dc94851de79b"
        },
        {
            "role": "permalink",
            "campaign_activity_id": "b7144593-831c-4e13-a95a-7ae5ddce9d86"
        }
    ]
}
  • Email campaign activities are different types of email interactions you can have with your contacts. For example, sending a initial email to contacts uses the primary_email activity. Resending an email to non-openers creates a resend activity. Constant Contact also provides you with a permalink activity that contains a permanent link to a web accessible version of your email.

Email campaign activities include content such as the email subject line, email headers, and custom HTML.

Example email campaign activity schema
{
	"format_type": 5,
	"from_email": "jdodge@example.com",
	"reply_to_email": "jdodge@example.com",
	"from_name": "Jake Dodge",
	"subject": "10 Holiday Specials for Cat Lovers",
	"current_status": "SCHEDULED",
	"html_content": "<html><body>[[trackingImage]]<a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a></body></html>",
	"preheader": "You don't want to miss this",
	"physical_address_in_footer": {
		"address_line1": "123 Maple Street",
		"address_line2": "Unit 1",
		"address_optional": "Near Boston Fire Station",
		"city": "Boston",
		"country_code": "US",
		"country_name": "United States",
		"organization_name": "Jake Dodge's Pet Supplies",
		"postal_code": "02451",
		"state_code": "MA"
	}
}

Email campaigns and email campaign activities allow you to better manage and report on different kinds of email marketing.

For example, if you are using the email reporting unique opens method to track performance, a resend email campaign activity will return data on a resend to non-openers email. If you want to get data on your initial send, you can use the primary_email email campaign activity. Both of these separate activities are associated with the same email campaign.

Format Types

Constant Contact uses format types to support different Constant Contact email editor versions and API email formats.

You can use the V3 API to create modern custom code emails (format type 5) or legacy custom code emails (format type 1).

Modern custom code emails support more features including using personalized content in emails and sending emails to segments.

Feature comparison between modern and legacy custom code emails
Feature Legacy Custom Code Modern Custom Code
Custom HTML Yes Yes
Inline CSS Yes Yes
CSS declarations in a <style> tag No Yes
Send the email to segments No Yes
Personalization tags (variables) Limited Full support including fallback text
Preview method processes personalization tags No Yes

For more information on using personalization tags to use contact, custom field, or account information in an email, see Designing HTML for Modern Custom Code Emails.

You can still retrieve, update, and schedule the other email format types, but you cannot use the V3 API to create them.

Email Campaign API Workflow

In order to successfully send an email to contacts, you must:

You currently cannot include the recipients of an email in the initial POST request to create an email campaign.

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!

DELETE a Single Email Campaign

DELETE /emails/{campaign_id}

Use this method to delete a specific email campaign (campaign_id) and any associated email campaign activities (campaign_activity_id). You cannot delete an email campaign when it has a Scheduled status. You can restore a deleted email campaign using the Constant Contact web user interface.

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!

POST Test Send an Email Campaign Activity

GET /emails/activities/{campaign_activity_id}/tests

Use this method to send a test email. Test emails allow you to verify how the email campaign activity will look before you send it to contacts.

Learn more about sending a test email.

Try it!

DELETE an Email Campaign

DELETE /emails/{campaign_id}

Use this method to delete an existing email campaign and all associated campaign activities.

You cannot delete email campaigns that have a Scheduled status.

Learn more about deleting an email campaign.

Try it!

GET an HTML Preview of an Email Campaign Activity

GET /emails/activities/{campaign_activity_id}/previews

Use this method to get an HTML preview of an email campaign activity. This HTML preview allows you to verify how the email campaign activity will look before you send it to contacts.

Learn more about getting an HTML preview of an email campaign activity.

Try it!