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. Theprimary_email
activity can be used to create an A/B email subject line test. In addition, resending an email to non-openers creates aresend
activity. Constant Contact also provides you with apermalink
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 custom code emails (format type 5). Custom code emails support more features including using personalized content in emails and sending emails to segments. You can still retrieve, update, and schedule the other email format types, but you cannot use the V3 API to create them.
For information on using personalization tags to use contact, custom field, or account information in an email, see Designing HTML for Custom Code Emails.
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.
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 toDRAFT
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 therole
(purpose) of each campaign activity within the email campaign, and thecampaign_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.
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.
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
.
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
.
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.
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.
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.
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.
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.
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.
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.
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.
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.
POST Resend to Non-openers for an Email Campaign Activity
POST /emails/activities/{campaign_activity_id}/non_opener_resends
Use this POST
method to schedule a resend to non-openers email campaign activity.
Learn more about getting resend to non-openers details for an email campaign activity.
GET Resend to Non-openers Details for an Email Campaign Activity
GET /emails/activities/{campaign_activity_id}/non_opener_resends
Use this GET
method to get details about a sent or scheduled resend to non-openers email campaign activity.
Learn more about getting resend to non-openers details for an email campaign activity.
DELETE a Resend to Non-openers for an Email Campaign Activity
DELETE /emails/activities/{campaign_activity_id}/non_opener_resends{resend_request_id}
Use this DELETE
method to delete (unschedule) a resend to non-openers email campaign activity.
Learn more about getting resend to non-openers details for an email campaign activity.
GET A/B Test Details for an Email Campaign Activity
GET /emails/activities/{campaign_activity_id}/abtest
Use this GET
method to get A/B test details for a primary email campaign activity.
Learn more about getting A/B test details for a primary email campaign activity.