Constant Contact V3 API Release Notes.

V3 API Release Notes introduce newly released endpoints and notable updates made available in each release.

Join the V3 API newsletter to learn about the latest API changes.

October 2020

New endpoints

Technology Partner Endpoints

This release provides support and documentation for the following Technology Partner Endpoints:

Endpoint (method/ route) & API Reference links Description
POST/partner/accounts Use this POST method to create a new Constant Contact client account under your technology partner account.

Only authorized technology partners have access to partner endpoints. To make authorized calls to partner endpoints, you must include your API key in the x-api-key header and the JSON Web Token (JWT) in the Authorization header. The JWT automatically expires in one hour (3,600 seconds) and cannot be refreshed. You must re-authenticate each time a JWT expires.

Reporting Endpoints

This release provides support and documentation for the following Email Reporting endpoints:

Endpoint (method/ route) & API Reference links Description
GET /reports/summary_reports/email_campaign_summaries Use this method to get a summary report listing the unique contact tracking activity counts for up to 500 sent email campaigns.

September

New endpoints

Technology Partner Feature

This V3 API release includes the several new technology partner endpoints. Technology partners use these endpoints to create and manage Constant Contact client accounts under their partner account.

Only authorized technology partners have access to partner endpoints. To make authorized calls to partner endpoints, you must include your API key in the x-api-key header and the JSON Web Token (JWT) in the Authorization header. The JWT automatically expires in one hour (3,600 seconds) and cannot be refreshed. You must re-authenticate each time a JWT expires.

The following technology partner endpoints are now available:

Endpoint (method/ route) & API Reference links Description
GET /partner/accounts/{encoded_account_id}/plan Use this GET method to get billing plan details for a Constant Contact client account.
PUT /partner/accounts/{encoded_account_id}/plan Use this PUT method to update the type of billing plan to use for a Constant Contact client account.
PUT /partner/accounts/{encoded_account_id}/status/cancel Use this PUT method to cancel the billing plan for a Constant Contact client account under your partner account.

Learn more about V3 API technology partner features.

Learn more about the technology partner program.

Signup to become a technology partner.

June 2020

New endpoints

Technology Partner Feature

This V3 API release includes the first of several new technology partner endpoints to be released. Technology partners use these endpoints to create and manage Constant Contact client accounts under their partner account.

Only authorized technology partners have access to partner endpoints. To make authorized calls to partner endpoints, you must include your API key in the x-api-key header and the JSON Web Token (JWT) in the Authorization header. The JWT automatically expires in one hour (3,600 seconds) and cannot be refreshed. You must re-authenticate each time a JWT expires.

The following technology partner endpoint is now available:

Endpoint (method/ route) & API Reference links Description
GET /partner/accounts Use this GET method to get all Constant Contact client accounts under your technology partner account.

Learn more about V3 API technology partner features.

Learn more about the technology partner program.

Signup to become a technology partner.

Segmentation Feature

This V3 API release supports segmenting contacts based on tracking data capturing how contacts interacted with your past email-campaign activities. The following segment endpoints are now available:

Endpoint (method/ route) & API Reference links Description
POST /segments Use this POST method to create a new segment that targets a subset of your contacts meeting your specific criteria.
GET /segments Use this GET method to get a list of all segments for an account.
GET /segments/{segment_id} Use this GET method to get details about a single segment.
DELETE /segments/{segment_id} Use this DELETE method to delete a segment from your account.
PUT /segments/{segment_id} Use this PUT method to update an existing segment's name (name) and/or contact selection criteria (segment_criteria).
PATCH /segments/{segment_id}/name Use this PATCH method to rename an existing segment.

Updates

You can now use a segment (segment_id) to:

  • Add the segment’s resulting contacts to list(s) using the bulk activities POST /activities/add_list_memberships endpoint.
  • Export the segment’s resulting contacts to a file using the bulk activities POST /activities/contact_exports endpoint.

January 2020

Updates

  • New Custom Code Email Type – The V3 API now supports a new type of custom code email (format_type 5). New custom code emails support:
    • Sending emails to segments.
    • Using personalization tags.
    • Adding your CSS declarations in a style tag in addition to supporting inline CSS.

    To ensure better email client support, Constant Contact will automatically convert your email to use inline CSS before sending it. For more information on creating this new type of custom code email, see Create an Email Campaign.

  • Fixes for UTF-8 Support – This release contains fixes for UTF-8 character support.

December 2019

New endpoints

Access token information method

This release provides support and documentation for the access token information method:

Endpoint (method/ route) & API Reference links Description
POST /token_info Use this POST method to return the list of OAuth2.0 scopes associated with a valid access token.

Account endpoints

This release provides support and documentation for the following Account Services endpoints:

Endpoint (method/ route) & API Reference links Description
POST /account/emails Add a new email address to the account associated with your bearer token. When you add a new email address to an account, Constant Contact automatically sends an email to that address with a link to confirm it. You can use email addresses that have a confirmed status to Create an Email Campaign.

Contacts endpoints

This release provides support and documentation for the following Contacts Endpoints:

Endpoint (method/ route) & API Reference links Description
POST /contacts/sign_up_form

Create a new contact or update an existing contact based on an email address. If the email address you provide is new, this method creates a new contact and returns a 201 response code. If the email address you provide already belongs to a contact, this method updates the contact and returns a 200 response.

Because this method updates existing contacts, you don't need to make a separate API call to check if the contact already exists in the account. Only use POST /contacts/sign_up_form if a contact gives you explicit permission to send them emails, such as through a sign up form.

Reporting endpoints

This release provides support and documentation for the following Email Reporting endpoints:

Endpoint (method/ route) & API Reference links Description
GET /reports/email_reports/{campaign_activity_id}/tracking/optouts Use this method to get a report listing each contact that clicked the unsubscribe link in the email campaign activity to opt-out from receiving emails sent from your Constant Contact account. This report includes contact information, such as the contact's email address, unique ID, and the opt-out date and time.
GET /reports/email_reports/{campaign_activity_id}/tracking/unique_opens Use this method to get a report listing details about the last time each contact opened the specified email campaign activity. This report includes basic contact information, such as the contact's email address and unique ID, the date and time they opened the email campaign activity, and the type of device they used to open it.
GET /reports/email_reports/{campaign_activity_id}/tracking/didnotopens Use this method to get a report listing each contact that was sent but did not open the specified email campaign activity. This report lists contact information such as the contact's email address and unique ID, and the date and time that the email campaign activity was sent.
GET /reports/email_reports/{campaign_activity_id}/tracking/forwards Use this method to get a report listing each time a contact forwarded the specified email campaign activity and general information about the contact, such as the contact's email address and unique ID, and the date and time the email campaign activity was forwarded.
GET /reports/email_reports/{campaign_activity_id}/tracking/bounces Use this method to get a report listing each contact that did not receive the email campaign activity because it was rejected (bounced) by their email service provider. This report includes information, such as the contact's email address and unique ID, and when and why the email activity bounced.

Updates

  • Contact CSV Exports – The V3 API now allows you to export the contact fields email_optin_source, email_optin_date, email_optout_source, email_optout_date, or email_optout_reason. For more information on exporting contacts, see Export Contacts to a CSV File.

October 2019

New endpoints

This release provides support and documentation for the following Email Campaign endpoints:

Endpoint (method/ route) & API Reference links Description
DELETE /emails/{campaign_id} Delete an existing email campaign and all associated email campaign activities. You cannot delete email campaigns that have a scheduled status.
POST /emails/activities/{campaign_activity_id}/tests Test send an email campaign activity. Test emails allow you to verify how the email campaign activity email looks before you send it to contacts.
GET /emails/activities/{campaign_activity_id}/previews Get an HTML preview of an email campaign activity. This preview allows you to verify how the email campaign activity email looks before you send it to contacts.
GET /emails/activities/{campaign_activity_id}/send_history Get the send history of an email campaign activity. The send history allows you to see each time you sent a specific email campaign activity to contacts and information about each send attempt.

V3 API Developer Portal Updates

A new Frequently Asked Questions (FAQs) tab has been added to the V3 API Developer Portal. Use the FAQs tab to quickly find answers and get links to related information. We will continue to add new FAQs over the upcoming months; so check back often.

New endpoints

This release provides support and documentation for the following Email Reporting endpoints:

These endpoints do not currently support filtering results using the report created_time timestamp.
Endpoint (method/ route) & API Reference links Description
GET /reports/email_reports/{campaign_activity_id}/tracking/sends Get a report listing the contacts to which a specified email campaign activity was sent and when it was sent. This report also includes basic contact information, such as the contact's email address and unique contact ID. The resulting report data is sorted by the most recent activity first. For more details, see Get a Sends Report for an Email Campaign Activity.
GET /reports/email_reports/{campaign_activity_id}/tracking/opens Get a report listing each time contacts opened the specified email campaign activity. This report includes basic contact information, such as the contact's email address and unique ID, the date and time they opened the email campaign activity, and the type of device they used to open it. The resulting report data is sorted by the most recent activity first. For more details, see Get an Opens Report for an Email Campaign Activity.
GET /reports/email_reports/{campaign_activity_id}/tracking/clicks Get a report listing each time contacts clicked a URL link in the specified email campaign activity. This report includes basic contact information, such as the contact's email address and unique ID, the date and time they clicked on the URL link, and the type of device used to open it. The resulting report data is sorted by the most recent activity first. For more details, see Get a Clicks Report for an Email Campaign Activity.

August 2019

New endpoints

This release provides support and documentation for the following Account Services endpoints:

Endpoint (method/ route) & API Reference links Description
GET /account/emails Get a collection of email addresses for the account associated with your bearer token. This method also return the status of the account email addresses. You can use email addresses that have a confirmed status to Create an Email Campaign.
PUT /account/summary Update account details for a Constant Contact user account, such as the organization name and account contact information.
GET /account/summary/physical_address Get the organization's physical address for the Constant Contact user account.
PUT /account/summary/physical_address Update the organization's physical address for the Constant Contact user account.

This release provides support and documentation for the following Email Reporting endpoints:

Endpoint (method/ route) & API Reference links Description
GET /reports/email_reports/{campaign_activity_id}/links Get a report that contains a list of each unique link URL in an email campaign activity and the number of unique contacts that clicked each link.

June 2019

New endpoints

This release provides support and documentation for the following new Email Campaign endpoints:

Endpoint (method/ route) & API Reference links Description
PUT /emails/activities/{campaign_activity_id} Update an email campaign activity.
POST /emails/activities/{campaign_activity_id}/schedules Schedule an email campaign activity.
GET /emails/activities/{campaign_activity_id}/schedules Get the schedule of an email campaign activity.
DELETE /emails/activities/{campaign_activity_id}/schedules Delete the schedule of an email campaign activity.

This release provides support and documentation for the following new Account Services endpoints:

Endpoint (method/ route) & API Reference links Description
GET /account/user/privileges Get the user privileges associated with your access token.
GET /account/summary Get a summary of account details, such as the organization name and account contact information for a specific account.

Updates

  • User Privileges – The V3 API now requires specific user privileges to access endpoints. Users in Constant Contact have different privileges depending on their role in an account. Users can have the role of account owner, account manager, or campaign creator. If you send an API request on behalf of a user that lacks the necessary privileges, the V3 API returns a 403 Forbidden error.

    For more information on the user privileges associated with each role in Constant Contact, see the User Roles and Privileges Overview. The User Roles and Privileges Overview and the API Reference both list the user privileges required by each V3 API endpoint and method. You can also use the Get User Privileges endpoint to return the user privileges associated with your access token.

  • Get a Deleted Contact by Email Address – The Get Contacts Collection endpoint now correctly returns results for deleted contacts when you search using an email address. For example, to return a deleted contact using their email address you can use GET https://api.cc.email/v3/contacts?email=deleted_email@example.com&status=deleted. The Get Contacts Collection endpoint does not return deleted contacts by default. Use the status query parameter with the value all or deleted to return deleted contacts.
  • Email Campaign Scheduling – Use the new Update an Email Campaign Activity method to add contact lists to an email campaign activity. This allows you to specify which contacts Constant Contact should send the email campaign activity to when you use the new Schedule an Email Campaign Activity method. You can also use the Get a Single Email Campaign Activity method to return the contact lists associated with an email campaign activity. Though the Update an Email Campaign Activity method also supports using segments to specify which contacts Constant Contact should send the email to, the fully segmentation workflow is not currently supported. The V3 API does not have methods to create new segments or get segment_id values yet.
  • Import Custom Field Data – You can now import custom field data when you use the Import Contacts using a CSV File and the Import Contacts using a JSON Payload methods. By prefixing the custom field name with cf:, you can import custom fields that have the same name as contact properties. The custom fields must already exist in the Constant Contact account you are using. You can import up to 25 different custom fields in each contact.

March 2019

New endpoints

This release provides support and documentation for the following new Email Campaign endpoints:

Endpoint (method/ route) & API Reference links Description</i>
POST /emails Create a new email campaign in your email campaign collection.
GET /emails Get a collection of email campaigns.
GET /emails/{campaign_id} Get a single email campaign and a list of associated campaign activities.
GET /emails/activities/{campaign_activity_id} Get details about a specific email campaign activity.
GET /emails/campaign_id_xrefs Get a collection of V2 and V3 campaign ids.
PATCH /emails Rename an existing email campaign.

Updates

  • Scopes – Use the new campaign_data scope to limit your application’s access to a user’s campaign data and to request that the user grant access to that data.
  • OAuth2 API – Content improvements made to the OAuth2 API documentation help to make the process easier to understand and the implementation easier to follow.
  • Delete contacts – You can now successfully DELETE a Contact using the v3 API Reference tester.
  • V3 API User Terms and Conditions – To see content updates made in the V3 API general terms and conditions for usage content, use the links located at the bottom of the My Applications tab.
  • Dev Portal updates - Updates were made to improve the V3 API Developer Portal user experience and documentation.