V3 API Release Notes introduce newly released endpoints and notable updates made available in each release.
June 2024
Updates and Feature Enhancements
Bulk Activities
Remove contacts from lists
When making a POST
call to the /activities/remove_list_memberships
endpoint, you can now choose from the following new source options to identify contacts to remove from list(s):
new_subscriber
- Set totrue
to remove all contacts that subscribed within the last 30 days to the specified target lists. Use with theexclude
object to exclude certain contacts (bycontact_id
) from being deleted from specified target lists.engagement_level
- removes all contacts that meet the selected engagement level (unqualified
,low
,medium
,high
) from your target lists. This property is mutually exclusive with all other source properties.tag_ids
- Specify an array of up to 50tag_id
s to remove all contacts with those tags from the specified target lists. This property is mutually exclusive with all other source properties.
If using all_active_contacts
or list_ids
as the source, you can now choose the new exclude
object to identify any contacts (by contact_id
) that you do not want to remove from the specified target lists.
Add Contacts to Lists
When making a POST
call to the /activities/add_list_memberships
endpoint, in the JSON request payload you can now choose from the following new source options to identify contacts to add to list(s):
new_subscriber
- Set totrue
to add all contacts that subscribed within the last 30 days to the specified target lists. Use with theexclude
object to exclude certain contacts (bycontact_id
) from being added to the specified target lists.engagement_level
- Adds all contacts that meet the selectedengagement_level
(unqualified
,low
,medium
,high
) to your target lists. This property is mutually exclusive with all other source properties.tag_ids
- an array of up to 50tag_ids
used to identify which tagged contacts to add to the destination lists.
If using all_active_contacts
or list_ids
as the source, you can now use the new exclude
object to identify contacts, by contact_id
, that you do not want to add to the target contact lists.
April 2024
Updates and Feature Enhancements
Partners
For partners that have the “SSO for all Client Accounts” feature enabled, to add a new SSO user to an existing client account, make a POST call to the /partner/accounts/{encoded_account_id}/users/sso endpoint .
December 2023
New Endpoints
The following new landing page reporting endpoints are now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_unique_contact_clicks | Get details for each contact that uniquely clicks a link on a specified landing page. |
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_unique_contact_sms_optins | Get details for each contact that clicked a link on a specified landing page to opt in to receiving SMS messages. |
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_unique_contact_opens | Get details for each contact that uniquely open a specific landing page. |
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_contact_opens | Get details for each time a contact opened a specific landing page. |
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_unique_contact_adds | Get details for each contact that was added to the account from a specific landing page. |
GET /reports/landing_pages/campaign_details/{campaign_activity_id}/p_unique_contact_updates | Get contact details for each contact in an account that was updated from a specific landing page. |
September 2023
New Endpoints
The following new Contact endpoint is now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /contacts/sms_engagement_history/{contact_id} | Use this method to get a contact's SMS engagement details, such as SMS consent and advertising frequency. |
Updates and Feature Enhancements
Contact Reporting
When making a GET request to the /reports/contact_reports/{contact_id}/activity_details
endpoint to get campaign tracking details, you can now choose to include new query parameters and tracking activity types.
New query parameters
-
tracking_activity_type
: This parameter allows you to choose the tracking activity types as an array (tracking_activity_type=em_sends&tracking_activity_type=em_opens
). This parameter is an alternative to using the existing thetracking_activities_list
which allows you to choose the tracking activity types as a comma-delimited string (em_clicks
,em_opens
). One from the two parameters must be included in the request. -
include_campaign_activity_names
: Use to return campaign activity names in the results. It is more efficient to not include campaign activity names in the results (false
). The default setting istrue
.
New landing page tracking activity types
p_contact_open
p_contact_click
p_contact_add
p_contact_update
August 2023
New Endpoints
The following endpoints are now available:
Endpoint (method/ route) & API Reference Links | Description |
---|---|
POST /activities/delete_custom_fields_activity | Use this method to create an asynchronous activity that removes up to 100 custom fields from contacts and deletes the custom fields from an account. |
March
New Endpoints
The following endpoints are now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
POST /BulkActivities/delete_lists | Use this method to create an asynchronous activity that deletes up to 100 contact lists from an account. |
Updates and Feature Enhancements
New Contact Filtering Options
-
Filter Contacts by SMS Status
Use the
sms_status
query parameter to retrieve only those contacts that have a specific SMS status. Valid values includeall
,explicit
,unsubscribed
,pending_confirmation
, andnot-set
. This parameter accepts one or more comma separated values. -
Get Contact Channel and Consent Details
To return SMS channel and consent details in the response, make a GET call to the following endpoints and set the
include
query parameter tosms_channel
:- GET /contacts
- GET /contacts/{contact_id}
-
Filter Contacts by Opt-out Dates
Use the
optout_after
andoptout_before
query parameters to return contacts that chose to opt-out before or after a specified date and time. Accepts ISO-8601 formatted dates.
December 2022
Updates and Feature Enhancements
OAuth2
The OAuth2 Device Flow is now available. Use this flow if your application runs on a device that is input constrained. For example, a command line application that cannot provide a web browser to users. For details, see Device Flow.
Activities
The following new query parameters are now available when making a POST call to the /activities/contact_exports
endpoint:
-
exclude
: The contacts (contact_ids) to exclude from the export activity. Applicable with either no source parameter specified or with list_ids or new_subscriber as the source. -
status
: Filter contact results by status; active, unsubscribed, or removed.
October 2022
New Endpoints
The following contacts endpoint is now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /contacts/counts | Use this method to get the total contact consent counts for each constent state. |
Updates and Feature Enhancements
Contact Lists
The following new query parameters are available when making a GET call to the /contacts_lists
endpoint:
-
name
: Enter the full name of a contact list to get details about that list. -
status
: Use to return only list details for lists that have a specific status. Options include:all
active
deleted
Email Reporting
When making a GET call to the /reports/email_reports/{campaign_activity_id}/links
endpoint, to include links with no clicks in the response results, use the new no_clicks
query parameter.
Depreciated Endpoints
The following authorization and token URLs are no longer supported:
https://api.cc.email/v3/idfed
https://idfed.constantcontact.com/as/token.oauth2
If you have not yet updated your existing application or created a new applications to use the new authorization and token URLs, see Update Your Applications to Use the New Authorization Service.
August 2022
New Endpoints
The following email campaign endpoints are now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
POST /emails/activities/{campaign_activity_id}/abtest | Use this method to create an A/B test for a primary email campaign activity. |
GET /emails/activities/{campaign_activity_id}/abtest | Use this method to get details about an A/B test for a primary email campaign activity. |
DELETE /emails/activities/{campaign_activity_id}/abtest | Use this method to delete an A/B test for a primary email campaign activity. |
The following technology partner endpoint is now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
POST Post /partner/accounts/{encoded_account_id}/account_operations/sync | Use this method to send an API request on behalf of a managed client account in your partnership. |
Updates and Feature Enhancements
Contacts
You can now search for contacts by specifying the date or date range when contacts were updated or created.
- by updated date - retrieve all contacts with properties updated after (
updated_after
) date or before (updated_before
) a specified date and time. To search for updated contacts within a date range, specify bothupdated_after
andupdated_before
dates. Accepts ISO-8601 formatted dates. -
by created date - retrieve all contacts created after (
created_after date
) or (created-before
) a specified date and time. To search for contacts created within a date range, specify bothcreated_after
andcreated_before
dates. Accepts ISO-8601 formatted dates.
February 2022
REQUIRED UPDATE!
As of March 31, 2022, support ends for applications that use our previous authorization management service and that use the following authorization and token URLs:
https://api.cc.email/v3/idfed
https://idfed.constantcontact.com/as/token.oauth2
As a result, you must update your existing application or create a new application. This includes updating your application code to use the new authorization and token URLs. For details about updating your existing applications, see Update Your Applications to Use the New Authorization Service.
To get details about the OAuth2 flow your application uses, see:
New PKCE Flow
The new service also adds support for the OAuth2 PKCE Flow. If you have an existing application that uses the Implicit Flow, Constant Contact strongly sugguests that you consider creating a new application integration using the more secure PKCE Flow.
JSON Web Tokens (JWT)
For added security, the Authorization Server now uses a JWT to transfer information (claims) between the Authorization Server and third party applications. JWT is an open standard RFC 7519.
You can view the claims of the JWT to access the scopes, expiration timestamp, and Constant Contact user ID for an access token. This information is available in the token itself. You do not need to make a separate HTTP request to access information about an access token.
Deprecate the token_info
Endpoint
As of March 31, 2022, the POST /token_info
endpoint is no longer supported. Instead, to view the scopes associated with an access token, parse the access token (JWT) claims.
Updates and Feature Enhancements
Technology Partners
Make V3 API calls on behalf of your managed client accounts
Many technology partners do all or some of the marketing on behalf of their managed client accounts. As a technology partner, you can now make V3 API calls on behalf of your managed client accounts. This allows you greater flexibility for performing marketing tasks and allows your managed client accounts to focus on their local clients and businesses. For more details, see Send API Requests on Behalf of Managed Client Accounts.
Filter on managed or unmanaged client accounts
When making a GET
call to the /partner/accounts
endpoint, you can now choose to filter your results to return all managed or all un-managed client accounts using the new account_type
parameter and specify either managed
or unmanaged
.
December 2021
New Endpoints
The following email campaign endpoints are now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
POST /emails/activities/{campaign_activity_id}/non_opener_resends. | Use this method to schedule a resend to non-openers email campaign activity. |
GET /emails/activities/{campaign_activity_id}/non_opener_resends. | Use this method to get details about a resend to non-openers email campaign activity. |
DELETE /emails/activities/{campaign_activity_id}/non_opener_resends/{resend_request_id}. | Use this method to delete (unschedule) a resend to non-openers email campaign activity. |
GET /emails/activities/{campaign_activity_id}/abtest | Use this method to get A/B test details for a primary email campaign activity. |
DELETE /emails/activities/{campaign_activity_id}/abtest | Use this method to delete an A/B test for a primary email campaign activity. |
Updates and feature enhancements
Technology Partners
Technology partners can now use Constant Contact’s Single Sign On (SSO) solution to allow their customers to access their integrated Constant Contact account without having to sign in with a separate username and password. SSO uses SAML 2.0 standards. Learn More about using SSO.
August
New Endpoints
Partner Webhooks
The following webhook endpoints are now available for technology partners:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /partner/webhooks/subscriptions/{topic_id} | Use this GET method to return webhook subscription information for a specific topic_id . For example, topic_id value 3 returns subscription information for cancelled accounts.
|
GET /partner/webhooks/subscriptions | Use this GET method to return a collection containing your application's webhook subscriptions. |
PUT /partner/webhooks/subscriptions/{topic_id} | Use this PUT method to subscribe your application to a topic_id or to update the callback URI for an existing subscription.
|
POST /partner/webhooks/subscriptions/{topic_id}/tests | Use this POST method to validate a webhook subscription by triggering a test notification for your chosen webhook topic_id . |
DELETE /partner/webhooks/subscriptions/{topic_id} | Use this DELETE method to unsubscribe from a webhook. |
Email Campaign Reports
The following reporting endpoints are now available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /reports/stats/email_campaign_activities/{campaign_activity_ids} | Use this method to get email campaign activity performance tracking statistics for up to ten campaign actvities. |
GET /reports/stats/email_campaigns/{campaign_ids} | Use this method to get email campaign performance tracking statistics for one or more campaigns, including the total number of times contacts interacted with your campaigns and how. |
Updates and feature enhancements
Segmentation
In addition to creating segments based on contact tags and tracking activity, you can now use contact details and contact list as segment selection criteria.
-
Contact details (contact): To include or exclude contacts based on contact details and custom contact fields, specify the contact data to use in the segment criteria. For example, you can create a segment that includes contacts that have birthdays in April, and that do not live in Maryland.
-
List memberships (contact list_membership): To limit the number of contacts Constant Contact evaluates, specify the contact list(s) to use. If no contact list is specified, all contacts in your account are evaluated.
Contacts
You can now use the V3 API to add and maintain up to 25 notes per contact.
- Use
POST /contacts
to add a note when creating a new contact. - Use
PUT /contacts/{contact_id}
to update an existing a note for a contact. - Use
GET /contacts
to get details about all your contacts including notes. - Use
GET /contacts/{contact_id}
to get all notes for a specific contact.
Email Campaigns
Legacy type 1
custom code emails are no longer supported and are automatically converted to the new modern type 5
custom code emails when a POST
call is made to the /email
endpoint.
May 2021
Partners can now specify an organization_phone
number when creating a new Constant Contact client account using POST /partner/accounts
.
April 2021
New endpoints
This release includes new activity endpoints used to manage a large number of tags and contact taggings.
Endpoint (method/ route) & API Reference links | Description |
---|---|
POST /activities/contacts_taggings_add | Use this method to create an asynchronous activity that adds one or more tags to all contacts meeting your contact filtering criteria. |
POST /activities/contacts_taggings_remove | Use this method to create an asynchronous activity that removes one or more tags from all contacts meeting your contact filtering criteria. |
POST /activities/contacts_tags_delete | Use this method to create an asynchronous activity that deletes one or more tags. |
Updates and feature enhancements
Email Campaigns
-
The
GET /emails
endpoint now supports searching for campaigns sent before or after a specified date, as well as within a specified date range. Note: Currently, renaming a campaign does not change theupdated_at
timestamp. -
As of this release, using
POST /emails
to create legacy-type email campaign activities (format_type
1) is no longer supported. Instead, to create custom HTML emails useformat_type
5.
March 2021
Updates and feature enhancements
This release includes support for the following:
New Segmentation Criteria
- When creating a segment, in the segment criteria you can choose to include or exclude contacts based on a contact’s taggings.
New Contacts Query Parameters and Properties
-
Use the
GET /contacts
newsegment_id
query parameter to get a list of all contacts that currently meet a segment’s criteria. -
Use the
GET /contacts
newtags
query parameter to get a list of all contacts that are tagged with one or more specified tags (tag_id
). -
Use the
GET
,PUT
, orPOST
/contact/{contact_id}
newtagging
property to view, update, or add tags to a single contact. -
Use
GET /contacts
and in theincludes
query parameter, specify the newtaggings
option to get tagging information returned for each contact in the results. -
Use
GET /contacts
and set the newinclude_count
query parameter totrue
to include the total number of contacts (contacts_count
) that meet the current contact search criteria in the response body.
New Bulk Activities support for exporting contact IDs
- When exporting contact details to a file using
POST /activities/contact_exports
, you can now use the request bodyfields
array to add contact IDs (contact_id
) to the CSV response.
February 2021
New endpoints
Contact Tags
This release includes the tag endpoint used to delete an existing tag. Upcoming releases will include endpoints used to assign, unassign, or remove tags from one or more contacts and changes to existing segment endpoints used to support tags as segment criteria.
The following tag endpoints are currently available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
DELETE /contact_tags/{tag_id} | Use this DELETE method to request an asynchronus actvity used to remove a tag from all contacts and then delete the tag. |
Learn more about using tags.
January 2021
New endpoints
Contact Tags
This release introduces the contact tags feature. Tags let you easily categorize and group contacts for the purpose of sending targeted messages without having to add contacts to new contact lists. The information used to determine which tags to create is often collected from surveys, membership registration, and sign-up forms. For example, you might create tags to identify groups of contacts that are volunteers, share interests, are loyalty card members, or share job roles (CFO, CEO, Purchaser, Human Resources).
This release includes the tag endpoints used to create, update, rename, and get details about tags. Upcoming releases will include the tag endpoint used to delete a tag, new tag activity endpoints used to assign, unassign, or remove tags from contacts, and changes to existing segment endpoints used to support tags as segment criteria.
The following tag endpoints are currently available:
Endpoint (method/ route) & API Reference links | Description |
---|---|
GET /contact_tags/{tag_id} | Use this GET method to get details about a specific tag. |
GET /contact_tags | Use this GET method to get details about all tags. |
POST /contact_tags | Use this POST method to create a new tag. |
PUT /contact_tags/{tag_id} | Use this PUT method to rename an existing tag. |
Learn more about using tags.
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 2020
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 |
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
, oremail_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:
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 thestatus
query parameter with the valueall
ordeleted
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.