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.

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.