Account Services

Use the account endpoints and methods to get account information.

GET User Privileges

Use this method to return the user privileges associated with your access token as an array of objects. This method returns all user privileges, including privileges the V3 API does not currently use. Constant Contact requires specific user privileges to make requests using the V3 API. For more information, see the User Privileges and Roles Overview.

Authorizations:
oauth2_implicitoauth2_access_code

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/account/user/privileges \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

GET a Summary of Account Details

Get account related details for a Constant Contact user account. Use the extra_fields query parameter to include the company_logo and/or physical_address details in the response body. For more details, see Get Account Summary Details.

User Privileges:
account:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
extra_fields
string <csv>
Enum: "physical_address" "company_logo"
Example: extra_fields=company_logo

Use the extra_fields query parameter to include the physical_address and/or company_logo details in the response body. Use a comma separated list to include both (physical_address, company logo).

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/account/summary?extra_fields=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{}

PUT (update) Account Details

Use this method to update account details for a Constant Contact account, such as the email address or phone number. This PUT method provides a partial update where only valid properties that you include in the request body are updated and excluded properties are not overwritten. For more details, see Put (update) Account Summary Details.

User Privileges:
account:update
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

In the request body, specify changes to account details by including and modifying all or select CustomerPut properties. Changes to read-only fields (encoded_account_id) are ignored.

contact_email
string

The confirmed email address that is associated with the account owner.

contact_phone
string <= 25 characters

The account owner's contact phone number (up to 25 characters in length).

country_code
string

The two-letter ISO 3166-1 code representing the organization's country.

first_name
string

The account owner's first name.

last_name
string

The account owner's last name.

organization_name
string

The name of the organization that is associated with this account.

organization_phone
string

The phone number of the organization that is associated with this account.

state_code
string

The two letter ISO 3166-1 code used to specify the state to associate with the account. This property is required if the country_code is US (United States).

time_zone_id
string

The time zone to use for the account; as defined in the IANA time-zone database (see http://www.iana.org/time-zones).

website
string

The organization's website URL.

Responses

Request samples

Content type
application/json
{
  • "contact_email": "InstaPrinz@gmail.com",
  • "contact_phone": "5081111212",
  • "country_code": "US",
  • "first_name": "Lola",
  • "last_name": "Zang",
  • "organization_name": "InstaPrinz",
  • "organization_phone": "333-333-3335",
  • "state_code": "MA",
  • "time_zone_id": "US/Eastern",
}

Response samples

Content type
application/json
{
  • "contact_email": "InstaPrinz@gmail.com",
  • "contact_phone": "5081111212",
  • "country_code": "US",
  • "encoded_account_id": "p07e1l8cdif9dl",
  • "first_name": "Lola",
  • "last_name": "Zang",
  • "organization_name": "InstaPrinz",
  • "organization_phone": "333-333-3335",
  • "state_code": "MA",
  • "time_zone_id": "US/Eastern",
}

GET the Physical Address for the Account

Use this method to get the address where the account's organization physically resides. The physical address is required to send emails and displays on the footer of every email that is sent from the account.

User Privileges:
account:read
Authorizations:
oauth2_implicitoauth2_access_code

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/account/summary/physical_address \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "address_line1": "123 Maple Street",
  • "address_line2": "Unit 1",
  • "address_line3": "Apartment 234",
  • "city": "Boston",
  • "state_code": "MA",
  • "state_name": "EXCLUDE if country_code is US.",
  • "postal_code": "02451",
  • "country_code": "US"
}

POST the Physical Address for the Account

Use this method to add the address where the account's organization physically resides. The physical address is required to send emails and displays on the footer of every email that is sent from the account. The country (country_code) where the account organization resides determines whether you use the state_code to specify United States (US) and Canada (CA) addresses, or use the state_name to specify all other countries.

User Privileges:
account:update
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

Include all AccountPhysicalAddress properties required for the specified country_code. If a required property is not included or incorrectly formatted, a 400 error message is returned. If the address already exists, a 409 error message is returned.

address_line1
required
string [ 1 .. 80 ] characters

Line 1 of the organization's street address.

address_line2
string [ 1 .. 80 ] characters

Line 2 of the organization's street address.

address_line3
string [ 1 .. 80 ] characters

Line 3 of the organization's street address.

city
required
string

The city where the organization is located.

state_code
string <= 2 characters

The two letter ISO 3166-1 code for the organization's state and only used if the country_code is US or CA. If not, exclude this property from the request body.

state_name
string

Use if the state where the organization is physically located is not in the United States or Canada. If country_code is US or CA, exclude this property from the request body.

postal_code
string

The postal code address (ZIP code) of the organization. This property is required if the state_code is US or CA, otherwise exclude this property from the request body.

country_code
required
string

The two letter ISO 3166-1 code for the organization's country.

Responses

Request samples

Content type
application/json
{
  • "address_line1": "123 Maple Street",
  • "address_line2": "Unit 1",
  • "address_line3": "Apartment 234",
  • "city": "Boston",
  • "state_code": "MA",
  • "state_name": "EXCLUDE if country_code is US.",
  • "postal_code": "02451",
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "address_line1": "123 Maple Street",
  • "address_line2": "Unit 1",
  • "address_line3": "Apartment 234",
  • "city": "Boston",
  • "state_code": "MA",
  • "state_name": "EXCLUDE if country_code is US.",
  • "postal_code": "02451",
  • "country_code": "US"
}

PUT (update) the Physical Address for an Account

Use this method to update the organization's physical address for the Constant Contact user account. The physical address is required to send emails and displays on the footer of every email that is sent from the account. To get the current physical address, make a GET call to /account/summary/physical_address. The country (country_code) where the account organization resides determines whether you use the state_code to specify United States (US) and Canada (CA) addresses, or use the state_name to specify all other countries. For more details, see Put (update) the Physical Address for the Account. You must have the role of Account Owner assigned to update account level details.

User Privileges:
account:update
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

Include all AccountPhysicalAddress properties required for the specified country_code and then update only those properties that you want to change. Excluding a non-read only field from the request body removes it from the physical address.

address_line1
required
string [ 1 .. 80 ] characters

Line 1 of the organization's street address.

address_line2
string [ 1 .. 80 ] characters

Line 2 of the organization's street address.

address_line3
string [ 1 .. 80 ] characters

Line 3 of the organization's street address.

city
required
string

The city where the organization is located.

state_code
string <= 2 characters

The two letter ISO 3166-1 code for the organization's state and only used if the country_code is US or CA. If not, exclude this property from the request body.

state_name
string

Use if the state where the organization is physically located is not in the United States or Canada. If country_code is US or CA, exclude this property from the request body.

postal_code
string

The postal code address (ZIP code) of the organization. This property is required if the state_code is US or CA, otherwise exclude this property from the request body.

country_code
required
string

The two letter ISO 3166-1 code for the organization's country.

Responses

Request samples

Content type
application/json
{
  • "address_line1": "123 Maple Street",
  • "address_line2": "Unit 1",
  • "address_line3": "Apartment 234",
  • "city": "Boston",
  • "state_code": "MA",
  • "state_name": "EXCLUDE if country_code is US.",
  • "postal_code": "02451",
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "address_line1": "123 Maple Street",
  • "address_line2": "Unit 1",
  • "address_line3": "Apartment 234",
  • "city": "Boston",
  • "state_code": "MA",
  • "state_name": "EXCLUDE if country_code is US.",
  • "postal_code": "02451",
  • "country_code": "US"
}

GET a Collection of Account Email Addresses

User Privileges:
account:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
confirm_status
string
Enum: "CONFIRMED" "C" "UNCONFIRMED" "U"

Use the confirm_status query parameter to search for account emails using the email status. Possible values are CONFIRMED or UNCONFIRMED. You can also abbreviate the values of this query parameter and use C or U.

role_code
string
Enum: "CONTACT" "C" "BILLING" "B" "JOURNALING" "J" "REPLY_TO" "R" "OTHER" "O"

Use the role_code query parameter to search for account emails that have a specific role. Each each email address in an account can have multiple roles or no role. Possible values are CONTACT, BILLING, REPLY_TO, JOURNALING, or OTHER. You can also abbreviate the value of this query parameter and use C,B,R,J, or O.

email_address
string

Use the email_address query parameter to search for a specific account email address.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/account/emails?confirm_status=SOME_STRING_VALUE&role_code=SOME_STRING_VALUE&email_address=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

POST Add an Account Email Address

Use this method to add a new email address to a Constant Contact account. If the email address you are adding already exists in the account the API will return a 409 conflict error.

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. After a user clicks that link, the account email status changes from UNCONFIRMED to CONFIRMED. You can use confirmed account email addresses in the email campaign from_email and reply_to_email headers. For more use case information, see Add an Account Email Address in the API guide.

User Privileges:
account:update
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

A JSON request payload containing the new email address you want to add to the Constant Contact account.

email_address
string <= 80 characters

The new email address you want to add to a Constant Contact account.

Responses

Request samples

Content type
application/json
{
  • "email_address": "dlang@example.com"
}

Response samples

Content type
application/json
{
  • "email_address": "dlang@example.com",
  • "email_id": 2,
  • "confirm_status": "UNCONFIRMED"
}

Bulk Activities

Bulk activities endpoints are used to manage large numbers of contacts, lists, and tags.

GET Activity Status Collection

This endpoint returns a collection of activities. Use the state query parameter to include only activities with a specific status (processing, completed, cancelled, failed, or time_out). Use the limit query parameter to define the number of activities returned per page. Learn more.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
integer [ 1 .. 500 ]
Default: 50
Example: limit=25

Specifies the number of results displayed per page of output, from 1 - 500, default = 50.

state
string
Enum: "processing" "completed" "cancelled" "failed" "timed_out"
Example: state=processing

Use this parameter to filter the response to include only activities in one of the following states: cancelled, completed, failed, processing, or timed_out.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/activities?limit=50&state=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "activities": [
    ],
  • "_links": {
    }
}

GET an Activity Status

This endpoint returns an activity status report.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
activity_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

The unique ID of the activity to GET

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/activities/%7Bactivity_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "source_file_name": "2016-21-04-contact_import.xls",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Export Contacts to a File

Use this method to create an activity that exports contacts and contact details to a CSV file. You can choose to export all contacts in your account (default) or you can use parameters to filter on which contacts to export. After Constant Contact finishes processing the activity, use the results link in the response body to retrieve the CSV file.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

A JSON payload that specifies the contacts (rows in the CSV file) and contact properties (columns in the CSV file) you want to export.

contact_ids
Array of strings <uuid> <= 500 items [ items <uuid > ]

Exports up to 500 specific contacts. This property is mutually exclusive with all other filtering criteria except withstatus.

list_ids
Array of strings <uuid> <= 50 items [ items <uuid > ]

Exports all of the contacts inside of up to 50 contact lists. This property is mutually exclusive with all other filtering criteria except with either status or exclude.

tag_ids
Array of strings <uuid> <= 50 items [ items <uuid > ]

Exports contacts assigned one or more of the tags (tag_id) specified. This property is mutually exclusive with all other filtering criteria.

new_subscriber
boolean

Set to true to only export contacts that subscribed within the last 30 days. Default setting is false. This property is mutually exclusive with all other filtering criteria except with either list_ids or exclude.

segment_id
integer

Specify the segment_id from which you want to export all contacts that meet the specified segment_criteria. You can only specify one segment_id. This property is mutually exclusive with all other filtering criteria.

fields
Array of strings
Items Enum: "first_name" "last_name" "contact_id" "email_address" "email_lists" "phone_number" "company_name" "job_title" "social_profiles" "website" "tag" "notes" "street" "street_1" "street_2" "city" "state" "intl_state" "zip" "country" "anniversary" "birthday" "birthday_day" "birthday_month" "source_name" "created_at" "updated_at" "email_optin" "email_permission" "email_update_source" "email_optin_source" "email_optin_date" "email_optout_date" "email_optout_source" "email_optout_reason" "sms_number" "sms_consent_date" "sms_status"

By default , all fields are returned. Use this array to only export specific contact fields. You must export email_address to successfully export email_optin_source, email_optin_date, email_optout_source, email_optout_date, or email_optout_reason.

status
string
Enum: "active" "unsubscribed" "removed"

Allows you to export only contacts that have a specific status value. This property is mutually exclusive with all other filtering criteria except with either contact_ids or list_ids.

object

Responses

Request samples

Content type
application/json
{
  • "contact_ids": [
    ],
  • "list_ids": [
    ],
  • "tag_ids": [
    ],
  • "new_subscriber": true,
  • "segment_id": 12,
  • "fields": [
    ],
  • "status": "unsubscribed",
  • "exclude": {
    }
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Retrieve Exported Contacts File

Use this endpoint to retrieve (GET) a CSV file containing exported contacts by providing the activity_id of a completed CSV export activity.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
file_export_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

The unique ID of the exported file provided in the results: section of the export contacts activity response.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/contact_exports/%7Bfile_export_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Delete Contacts in Bulk

Use this endpoint to bulk delete contacts in an account. Contacts to delete are specified by contact_id (up to 500), or by list_id (up to 50 lists); all contacts that are members of the list_ids are deleted. Deleted contacts won’t receive email from you, and they don’t count as active contacts. Unlike unsubscribed contacts, deleted contacts can be added back to an account. Learn how to revive deleted contacts.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The request body contains an array of contact_ids or list_ids. All contact_ids provided are deleted, or all members of each specified list_id are deleted.

contact_ids
Array of strings <uuid> <= 500 items [ items <uuid > ]

Specify up to 500 contacts by contact_id to delete; mutually exclusive with list_ids.

list_ids
Array of strings <uuid> <= 50 items [ items <uuid > ]

The contacts on the lists (up to 50) specified will be deleted; mutually exclusive with contact_ids.

Responses

Request samples

Content type
application/json
{
  • "contact_ids": [
    ],
  • "list_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Import Contacts using a CSV File

This multipart method creates an asynchronous background job that adds or updates contacts by importing a CSV file containing contact information. Do not use a Content-Type header value with this method.

Importing a new contact email address automatically sets the contact's permission_to_send property as implicit and the opt_in_source property as Account. Importing an existing contact only updates the contact properties you include in the request. Importing contacts with sms_numbers requires using the sms_permission_to_send parameter to specify permissions for all contacts being imported. Set to explicit to specify that all contacts either provided explicit permission. Set to not_set if permission was not provided. If explicit, you must also include the sms_consent_date as a column header to include the date the contact consented to receiving SMS messages. Contacts must have either an email address or an SMS number defined.

The CSV file has a maximum of 40,000 lines including the header row (39,999 contacts) and a maximum file size of 4 megabytes (MB). Lines above the 40,000 line maximum are not processed. If the request body exceeds 4 MB, only the contacts contained in the first 4 MB are imported and the remaining data is dropped.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: multipart/form-data
required
file
required
string <binary>

The CSV file you are importing must include either email or sms_number as a column heading. Other properties you can include using column headings are: first_name. last_name, phone, job_title, anniversary, birthday_day, birthday_month, company_name, street, street2, city, state, zip, country, and sms_consent_date.

If adding an sms_number, you must also include the sms_permission_to_send parameter and set it to either not_set or explicit. If explicit, requires including sms_consent_date as a column header to specify the date the contact consented to receiving SMS messages.

You can also use custom fields as column headings. Enter the custom field name prefixed with cf: as the column heading. For example, use cf:first_name as the header name if you have a custom field named "first_name". The custom field must already exist in the Constant Contact account you are using. Depending on the custom field data type, you can enter dates or strings as the value of the custom field. Each contact can contain up to 25 different custom fields.

list_ids
required
Array of strings <= 50 items

Specify which contact lists you are adding all imported contacts to as an array of up to 50 contact list_id values.

sms_permission_to_send
string
Enum: "not_set" "explicit"

If importing contact sms_numbers, use this parameter to specify how SMS consent was provided. If all contacts in the file provided their consent, set to explicit and include each contact's sms_consent_date. If all contacts in the file have not yet provided consent, set to not_set (sms_consent_date is not required). You cannot message a contact that does not have a sms consent date set.

Responses

Request samples

curl --request POST \
  --url https://api.cc.email/v3/activities/contacts_file_import \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: multipart/form-data'

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:40.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "source_file_name": "2016-21-04-contact_import.xls",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Import Contacts using a JSON Payload

Use this method to create an asynchronous background job that adds new contacts or updates existing contacts by importing a JSON payload. This method requires a request body that contains the contact data you are importing and the contact lists to which you want to add the imported contacts. A contact's data must include an email address and/or sms_number. The sms_number must be a US phone number to associate with the contact's SMS-enabled phone. Valid formats are 1231231234 or 123-123-1234 (the country code must be valid).

Importing a new contact using this method automatically sets the contact's email permission_to_send property to implicit and the opt_in_source property as Account. Importing an existing contact only updates the contact properties you include in the request. For each contact, you can import up to three addresses and three phone numbers. International phone numbers are currently not supported.

To import custom fields, prefix the custom field name with cf: and add it as a contact property. For example, use the property name cf:first_name if you have a custom field named first_name. The custom field must already exist in the Constant Contact account you are using. Each contact can contain up to 25 custom fields.

To include a contact's sms_number, if the contact provided explicit permission to receive SMS messages, you must set the sms_permission_to_send property to explicit and specify the date of consent using the sms_consent_date column header. If explicit permission was not provided, set sms_permission_to_send to not_set (the sms_consent_date is not required). If the sms_consent_date is not set, SMS messages cannot be sent to contacts and sms_permission_to_send defaults to not_set. Valid value formats for sms_consent_date` include MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY.

The request body payload has a maximum size of 4 megabytes (MB). If the request body exceeds 4 MB, this method only imports the first 4 MB and drops the remaining data. Use the activity URL to check the status of the import activity request.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON request payload that contains the contact data and contact lists for the import.

required
Array of objects (JsonImportContact)

An array containing the contacts to import.

list_ids
required
Array of strings <uuid> [ 1 .. 50 ] items [ items <uuid > ]

Specify which contact lists you are adding all imported contacts to as an array of up to 50 contact list_id string values.

sms_permission_to_send
string
Enum: "explicit" "not_set"

Specifies if the contact gave explicit SMS permission or if the SMS permission was not set (not_set). If `explicit, the sms_consent_date must be provided.

Responses

Request samples

Content type
application/json
{
  • "import_data": [
    ],
  • "list_ids": [
    ],
  • "sms_permission_to_send": "explicit"
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:40.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "source_file_name": "2016-21-04-contact_import.xls",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Remove Contacts from Lists

Use this method to create an activity that removes contacts from one or more contact lists. Use the properties in the source object to remove specific contacts from your lists. Use the list_ids array to specify the target lists from which contacts are removed. Optionally, if the source is all_active_contacts (billable) or list_ids, use the exclude object to exclude specific contacts from being removed from the destination lists.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload used to create the Remove Contacts from Lists' activity

required
object

Specifies the contacts to remove from your target list(s) using one of several mutually exclusive properties.

object
list_ids
required
Array of strings <uuid> <= 0 items [ items <uuid > ]

Specify up to 50 target list_ids from which to remove contacts.

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "exclude": {
    },
  • "list_ids": [ ]
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Add Contacts to Lists

Use this method to create an activity that adds contacts to one or more lists. Each contact can be a member of up to 50 lists. Use the properties in the source object to specify the contacts you want to add to lists. Use the list_ids array to specify which lists you want to add your source contacts to.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload used to create the 'add contacts to lists' activity

required
object

The source object specifies which contacts you are adding to your targeted lists using one of four mutually exclusive properties.

object
list_ids
required
Array of strings <uuid> <= 50 items [ items <uuid > ]

Specifies which lists (up to 50) you are adding your source contacts to.

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "exclude": {
    },
  • "list_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Delete Contact Lists

Use this endpoint to delete up to 100 contact lists in an account.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

An array of list_id's to delete.

list_ids
required
Array of strings <uuid> <= 100 items [ items <uuid > ]

The array of contact lists list_id to delete.

Responses

Request samples

Content type
application/json
{
  • "list_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "af86135c-8740-11eb-8abf-fa163ef30864",
  • "state": "initialized",
  • "started_at": "2019-12-12T15:38:24Z",
  • "completed_at": "2019-12-12T15:38:24Z",
  • "created_at": "2019-12-12T15:38:24Z",
  • "updated_at": "2019-12-12T15:38:24Z",
  • "percent_done": 25,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Remove Tags from Contacts

Use this method to create an asynchronous activity that removes one or more tags from all contacts meeting your contact filtering criteria. Filtering criteria must include the source type used to identify contacts from which the specified tags (tag_id) are removed. Source types are mutually exclusive. If the specified source is either all_active_contacts or list_ids, you can optionally choose to exclude specified contacts by contact_id. Use the activity link in the results to check the status of your request." For more use case information, see "Remove Tags from Contacts

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload used to create an asynchronous activity that removes tags from contacts meeting your specified contact filtering criteria.

required
object

Select the source used to identify contacts to which a tag is added or removed. Source types are mutually exclusive.

object

Use to exclude specified contacts from being added or removed from a tag. Only applicable if the specified source is either all_active_contacts (billable) or list_ids.

tag_ids
required
Array of strings <uuid> <= 50 items [ items <uuid > ]

An array of tags (tag_id) to add to all contacts meeting the specified source criteria.

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "exclude": {
    },
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "af86135c-8740-11eb-8abf-fa163ef30864",
  • "state": "initialized",
  • "started_at": "2019-12-12T15:38:24Z",
  • "completed_at": "2019-12-12T15:38:24Z",
  • "created_at": "2019-12-12T15:38:24Z",
  • "updated_at": "2019-12-12T15:38:24Z",
  • "percent_done": 25,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Add Tags to Contacts

Use this method to create an asynchronous activity that adds one or more tags to all contacts meeting your contact filtering criteria. Use the source type to identify contacts from which the specified tags (tag_id) are added. Source criteria are mutually exclusive. If the source is all_active_contacts or list_ids, you can optionally choose to exclude contacts by contact_id. Use the activity link in the results to check the status of your request. For more use case information, see "Add Tags to Contacts

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload used to create an asynchronous activity that adds tags to contacts that meet your specified contact filtering criteria.

required
object

Select the source used to identify contacts to which a tag is added or removed. Source types are mutually exclusive.

object

Use to exclude specified contacts from being added or removed from a tag. Only applicable if the specified source is either all_active_contacts (billable) or list_ids.

tag_ids
required
Array of strings <uuid> <= 50 items [ items <uuid > ]

An array of tags (tag_id) to add to all contacts meeting the specified source criteria.

Responses

Request samples

Content type
application/json
{
  • "source": {
    },
  • "exclude": {
    },
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "af86135c-8740-11eb-8abf-fa163ef30864",
  • "state": "initialized",
  • "started_at": "2019-12-12T15:38:24Z",
  • "completed_at": "2019-12-12T15:38:24Z",
  • "created_at": "2019-12-12T15:38:24Z",
  • "updated_at": "2019-12-12T15:38:24Z",
  • "percent_done": 25,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Delete Tags

Use this method to create an asynchronous activity that deletes up to 500 tags. Deleted tags are automatically removed from tagged contacts. Use the tag_ids array of string values in the request body to specify which tags to delete.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

An array of string values (tag_ids) to delete.

tag_ids
required
Array of strings <uuid> <= 500 items [ items <uuid > ]

The tag IDs (tag_ids) to delete.

Responses

Request samples

Content type
application/json
{
  • "tag_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "activity_id": "af86135c-8740-11eb-8abf-fa163ef30864",
  • "state": "initialized",
  • "started_at": "2019-12-12T15:38:24Z",
  • "completed_at": "2019-12-12T15:38:24Z",
  • "created_at": "2019-12-12T15:38:24Z",
  • "updated_at": "2019-12-12T15:38:24Z",
  • "percent_done": 25,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

Delete Custom Fields

Use this endpoint to delete up to 100 custom fields for an account.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

An array of custom_field_id's to delete.

custom_field_ids
required
Array of strings <uuid> <= 0 items [ items <uuid > ]

The array of custom field IDs to delete.

Responses

Request samples

Content type
application/json
{
  • "custom_field_ids": [ ]
}

Response samples

Content type
application/json
{
  • "activity_id": "86b90820-cc52-11ea-9dad-fa163e3d9194",
  • "state": "initialized",
  • "started_at": "2016-01-23T13:48:44.108Z",
  • "completed_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 75,
  • "activity_errors": [
    ],
  • "_links": {
    }
}

Contacts

Endpoints and methods to get, create, delete, and update one or more contacts.

GET a Contact

This endpoint GETs a specific contact resource (contact_id). Use the include query parameter to add any of the available contact sub-resources to the response payload.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of contact to GET

query Parameters
include
string <csv>
Enum: "custom_fields" "list_memberships" "phone_numbers" "street_addresses" "taggings" "notes"
Example: include=custom_fields,list_memberships

Use include to specify which contact sub-resources to include in the response. Use a comma to separate multiple sub-resources. Valid values: custom_fields, list_memberships, phone_numbers, street_addresses, notes, and taggings.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contacts/%7Bcontact_id%7D?include=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "email_address": {
    },
  • "first_name": "Debora",
  • "last_name": "Lang",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "anniversary": "2006-11-15",
  • "update_source": "Contact",
  • "create_source": "Account",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "deleted_at": "2016-07-08",
  • "custom_fields": [
    ],
  • "phone_numbers": [
    ],
  • "street_addresses": [
    ],
  • "list_memberships": [
    ],
  • "taggings": [
    ],
  • "notes": [
    ],
  • "sms_channel": {
    }
}

PUT (update) a Contact

The PUT method updates an existing contact. You must include the update_source property in the PUT request payload. To restore a deleted contact you must specify the update_source as Account. When updating any resource using PUT, all properties are updated, overwriting all previous values. Any properties left blank or not included in the request are overwritten with null value - however this does not apply to contact subresources.

Add or change any of the subresources by including them in the PUT request payload. Omitted subresources are not overwritten with null. If the contact being updated is deleted, the contact will be revived. If email_address is specified:

**Only use this method when a contact gives you their explicit permission to send them an email. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

If sms_channel is specified:

Only use this method when a contact gives you their explicit permission to send them an SMS. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of contact to update

Request Body schema: application/json
required

JSON payload defining the contact object, with updates. Any properties left blank or not included in the PUT payload are overwritten with null value - does not apply to contact subresources.

object (EmailAddressPut)

The contact's email address and related properties.

first_name
string <= 50 characters

The contact's first name

last_name
string <= 50 characters

The contact's last name

job_title
string <= 50 characters

The contact's job title

company_name
string <= 50 characters

Name of the company the contact works for.

birthday_month
integer

Accepts values from 1-12; must be used with birthday_day

birthday_day
integer

Accepts values from 1-31; must be used with birthday_month

anniversary
string <= 10 characters

The anniversary date; Accepted formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D, MM-DD-YYYY, M-D-YYYY

update_source
required
string
Enum: "Account" "Contact"

Identifies who last updated the contact; valid values are Contact or Account.

Array of objects (ContactCustomField) <= 25 items

Array of up to 25 custom_field subresources.

Array of objects (PhoneNumberPut) <= 3 items

Array of up to 3 phone_numbers subresources.

Array of objects (StreetAddressPut) <= 3 items

Array of up to 3 street_addresses subresources.

list_memberships
Array of strings <uuid> <= 50 items [ items <uuid > ]

Array of up to 50 list_ids to which the contact is subscribed.

taggings
Array of strings <uuid> <= 50 items [ items <uuid > ]

Array of tags (tag_id) assigned to the contact, up to a maximum of 50.

Array of objects (Note) <= 150 items

An array of notes about the contact listed by most recent note first.

object (ContactSmsChannel)

Responses

Request samples

Content type
application/json
{
  • "email_address": {
    },
  • "first_name": "Debora",
  • "last_name": "Lang",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "anniversary": "2006-11-15",
  • "update_source": "Account",
  • "custom_fields": [
    ],
  • "phone_numbers": [
    ],
  • "street_addresses": [
    ],
  • "list_memberships": [
    ],
  • "taggings": [
    ],
  • "notes": [
    ],
  • "sms_channel": {
    }
}

Response samples

Content type
application/json
{
  • "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "email_address": {
    },
  • "first_name": "Debora",
  • "last_name": "Lang",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "anniversary": "2006-11-15",
  • "update_source": "Contact",
  • "create_source": "Account",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "deleted_at": "2016-07-08",
  • "custom_fields": [
    ],
  • "phone_numbers": [
    ],
  • "street_addresses": [
    ],
  • "list_memberships": [
    ],
  • "taggings": [
    ],
  • "notes": [
    ],
  • "sms_channel": {
    }
}

DELETE a Contact

Deletes the contact identified by the contact_id path parameter. Deleted contacts won't receive email from you, and they don't count as active contacts. Unlike unsubscribed contacts, deleted contacts can be revived, or added back to an account. Learn how to revive deleted contacts.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of contact to DELETE

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/contacts/%7Bcontact_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

GET Contacts Collection

Use this method to return a collection of contacts. Use the query parameters to search for contacts that match specific contact properties and sub-resource properties as criteria. For example, you can search using the contact's email address, lists memberships, and by the date range that a contact was created or updated. Use the limit query parameter to limit the number of results returned per page. Use the include query parameter to include contact sub-resources in the response and include_count to include the total number of contacts that meet your specified search criteria.

By default, this method returns all contacts that are not deleted. Use the status query parameter with the value all to return all contacts including deleted contacts.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
status
string <csv>
Enum: "all" "active" "deleted" "not_set" "pending_confirmation" "temp_hold" "unsubscribed"

Use the status query parameter to search for contacts by status. This parameter accepts one or more comma separated values: all, active, deleted, not_set, pending_confirmation, temp_hold, and unsubscribed.

email
string
Example: email=xyz@example.com

Use the email query parameter to search for a contact using a specific email address.

lists
string <= 25
Example: lists=04fe9a-a579-43c5-bb1a-58ed29bf0a6a,04fe9a-a579-43c5-bb1a-58ed29bf0a6a,04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Use the lists query parameter to search for contacts that are members of one or more specified lists. Use a comma to separate multiple list_id values, up to a maximum of 25.

segment_id
string <= 1
Example: segment_id=14

Use to get contacts that meet the segment criteria for a single specified segment_id. This query parameter can only be combined with the limit query parameter. When using the segment_id query parameter, the V3 API may return a 202 response code instead of a 200 response. The 202 response code indicates that your request has been accepted, but not fully completed. Retry sending your API request to return the completed results and a 200 response code.

tags
string <uuid> <= 50
Example: tags=fa85f64-5717-4562-b3fc-2c963f66afa6

Use to get contact details for up to 50 specified tags. Use a comma to separate each tag_id.

updated_after
string <date-time>
Example: updated_after=2022-01-01T16:37:59.091Z

Use updated_after to search for contacts that have been updated after the date you specify. To search for updated contacts within a date range, specify both updated_after and updated_before dates. Accepts ISO-8601 formatted dates.

updated_before
string <date-time>
Example: updated_before=2022-07-16T16:37:59.091Z

Use updated_before to search for contacts that have been updated before a specified date. To search for updated contacts within a date range, specify both updated_after and updated_before dates. Accepts ISO-8601 formatted dates.

created_after
string <date-time>
Example: created_after=2021-01-01T16:37:59.091Z

Use created_after to search for contacts created after a specified date. To search for contacts created within a date range, specify both created_after and created_before dates. Accepts ISO-8601 formatted dates.

created_before
string <date-time>
Example: created_before=2022-07-16T16:37:59.091Z

Use created_before to search for contacts created before a specified date. To search for contacts created within a date range, specify both created_after and created_before dates. Accepts ISO-8601 formatted dates.

optout_after
string <date-time>
Example: optout_after=2022-11-16T16:20:59.091Z

Use optout_after to search for contacts that unsubscribed after a specified date.

optout_before
string <date-time>
Example: optout_before=2022-11-16T16:20:59.091Z

Use optout_before to search for contacts that unsubscribed before a specified date.

include
string <csv>
Enum: "custom_fields" "list_memberships" "phone_numbers" "street_addresses" "taggings" "notes"
Example: include=custom_fields,list_memberships

Use include to specify which contact sub-resources to include in the response. Use a comma to separate multiple sub-resources. Valid values: custom_fields, list_memberships, taggings, notes,phone_numbers, street_addresses.

sms_status
string <csv>
Enum: "all" "explicit" "unsubscribed" "pending_confirmation" "not_set"

Use to get contacts by their SMS status. This parameter accepts one or more comma separated values: all, explicit, unsubscribed, pending_confirmation, not_set.

include_count
boolean
Example: include_count=true

Set include_count=true to include the total number of contacts (contacts_count) that meet all search criteria in the response body.

limit
integer [ 1 .. 500 ]
Default: 50
Example: limit=25

Specifies the number of results displayed per page of output in the response, from 1 - 500, default = 50.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contacts?status=SOME_STRING_VALUE&email=SOME_STRING_VALUE&lists=SOME_STRING_VALUE&segment_id=SOME_STRING_VALUE&tags=SOME_STRING_VALUE&updated_after=SOME_STRING_VALUE&updated_before=SOME_STRING_VALUE&created_after=SOME_STRING_VALUE&created_before=SOME_STRING_VALUE&optout_after=SOME_STRING_VALUE&optout_before=SOME_STRING_VALUE&include=SOME_STRING_VALUE&sms_status=SOME_STRING_VALUE&include_count=SOME_BOOLEAN_VALUE&limit=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "contacts": [
    ],
  • "contacts_count": 3249,
  • "_links": {
    },
  • "status": "processing"
}

POST (create) a Contact

Creates a new contact resource. You must include the create_source property and at least one of the following properties: first_name, last_name, a unique email_address (specified using the EmailAddress object), or the sms_channel property (specified using the ContactSmsChannel object).

If `email_address` is specified: **Only use this method when a contact gives you their explicit permission to send them an email. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

If sms_channel is specified:

Only use this method when a contact gives you their explicit permission to send them an SMS. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload defining the contact

object (EmailAddressPost)

The contact's email address and related properties.

first_name
string <= 50 characters

The first name of the contact.

last_name
string <= 50 characters

The last name of the contact.

job_title
string <= 50 characters

The job title of the contact.

company_name
string <= 50 characters

The name of the company where the contact works.

create_source
string
Enum: "Account" "Contact"

Describes who added the contact; valid values are Contact or Account. Your integration must accurately identify create_source for compliance reasons; value is set on POST, and is read-only going forward.

birthday_month
integer

The month value for the contact's birthday. Valid values are from 1 through 12. The birthday_month property is required if you use birthday_day.

birthday_day
integer

The day value for the contact's birthday. Valid values are from 1 through 31. The birthday_day property is required if you use birthday_month.

anniversary
string <= 10 characters

The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY.

Array of objects (ContactCustomField) <= 25 items

Array of up to 25 custom_field key value pairs.

Array of objects (PhoneNumberPut) <= 3 items

Array of up to 3 phone numbers subresources.

Array of objects (StreetAddressPut) <= 3 items

Array of up to 3 street address subresources.

list_memberships
Array of strings <uuid> <= 50 items [ items <uuid > ]

Array of list_ids to which the contact is being subscribed, up to a maximum of 50.

taggings
Array of strings <uuid> <= 50 items [ items <uuid > ]

Array of tags (tag_id) assigned to the contact, up to a maximum of 50.

Array of objects (Note) <= 150 items

An array of notes about the contact.

object (ContactSmsChannel)

Responses

Request samples

Content type
application/json
{
  • "email_address": {
    },
  • "first_name": "Debora",
  • "last_name": "Lang",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "create_source": "Account",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "anniversary": "2006-11-15",
  • "custom_fields": [
    ],
  • "phone_numbers": [
    ],
  • "street_addresses": [
    ],
  • "list_memberships": [
    ],
  • "taggings": [
    ],
  • "notes": [
    ],
  • "sms_channel": {
    }
}

Response samples

Content type
application/json
{
  • "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "email_address": {
    },
  • "first_name": "Debora",
  • "last_name": "Lang",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "anniversary": "2006-11-15",
  • "update_source": "Contact",
  • "create_source": "Account",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "deleted_at": "2016-07-08",
  • "custom_fields": [
    ],
  • "phone_numbers": [
    ],
  • "street_addresses": [
    ],
  • "list_memberships": [
    ],
  • "taggings": [
    ],
  • "notes": [
    ],
  • "sms_channel": {
    }
}

Create or Update a Contact

Use this method to create a new contact or update an existing contact. In the request body, this method requires including the list_memberships array as well as either the contact's email_address string or sms_channel object which includes the contact's SMS number. The information you specify determines if a new contact is either created (the email address or SMS number does not already exist in the account), or if an existing contact is updated (the email address or SMS number already exists). The SMS product feature does not need to be enabled to include a contacts SMS details.

Updates to existing contacts are partial updates. This method only updates the contact properties you include in the request body. Updates append new contact lists or custom fields to the existing list_memberships or custom_fields arrays. If email_address is specified:

Only use this method when a contact gives you their explicit permission to send them an email. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

If sms_channel is specified:

Only use this method when a contact gives you their explicit permission to send them an SMS. It is a violation of anti-spam and telemarketing laws, as well as a serious violation of the Constant Contact Terms of Service to use the Opt-in features of the API to opt a contact back in without his or her own action and consent.

When this method creates a new contact, it returns a 201 response code.When this method updates an existing contact, it returns a 200 response code. Updating a deleted contact restores the contact.

The method automatically modifies the contact's permission_to_send and opt_in_source properties depending on the Confirmed Opt-In Constant Contact account setting:

If Confirmed Opt-in is enabled, this method automatically sets the permission_to_send property as pending_confirmation for new contacts. If Confirmed Opt-in is disabled, this method automatically sets the permission_to_send property as explicit and the opt_in_source property as Contact for new contacts. Updated contacts have their permission_to_send property set as explicit.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

A JSON request body payload that contains the contact resource you are creating or updating. The request body must contain the email_address property and list_memberships array, or the sms_channel object.

email_address
string <= 50 characters

The email address for the contact. This method identifies each unique contact using their email address. If the email address exists in the account, this method updates the contact. If the email address is new, this method creates a new contact.

first_name
string <= 50 characters

The first name of the contact.

last_name
string <= 50 characters

The last name of the contact.

job_title
string <= 50 characters

The job title of the contact.

company_name
string <= 50 characters

The name of the company where the contact works.

phone_number
string <= 25 characters

The phone number for the contact.

list_memberships
required
Array of strings <uuid> [ 1 .. 50 ] items [ items <uuid > ]

The contact lists you want to add the contact to as an array of up to 50 contact list_id values. You must include at least one list_id.

Array of objects (CreateOrUpdateContactCustomField) <= 50 items

The custom fields you want to add to the contact as an array of up to 50 custom field objects.

anniversary
string

The anniversary date for the contact. For example, this value could be the date when the contact first became a customer of an organization in Constant Contact. Valid date formats are MM/DD/YYYY, M/D/YYYY, YYYY/MM/DD, YYYY/M/D, YYYY-MM-DD, YYYY-M-D,M-D-YYYY, or M-DD-YYYY.

birthday_month
integer

The month value for the contact's birthday. Valid values are from 1 through 12. The birthday_month property is required if you use birthday_day.

birthday_day
integer

The day value for the contact's birthday. Valid values are from 1 through 31. The birthday_day property is required if you use birthday_month.

object
sms_channel
string

The contact's SMS compatible phone number.

Responses

Request samples

Content type
application/json
{
  • "email_address": "jdodge@example.com",
  • "first_name": "Jake",
  • "last_name": "Dodge",
  • "job_title": "Musician",
  • "company_name": "Acme Corp.",
  • "phone_number": "(555) 555-1212",
  • "list_memberships": [
    ],
  • "custom_fields": [
    ],
  • "anniversary": "11-15-2006",
  • "birthday_month": 11,
  • "birthday_day": 24,
  • "street_address": {
    },
  • "sms_channel": "string"
}

Response samples

Content type
application/json
{
  • "contact_id": "ab7ab702-b935-11e9-8a58-fa163e6b01c1",
  • "action": "created"
}

GET a collection of V2 and V3 API contact IDs

Use this endpoint to migrate your locally stored V2 contact ids to the new V3 format. Developers are expected to use this endpoint sparingly. This endpoint is NOT intended for regular or repeated use. Constant Contact will eventually deprecate and remove this endpoint.

This GET call retrieves a collection of cross-referenced contact sequence IDs (id used in the V2 API) and UUIDs (contact_id used in the V3 API). This endpoint is intended for developers who have an existing V2 API integration, and are migrating their users to a new V3 API integration. The V2 and V3 APIs use different resource ID formats. Use the sequence_ids query parameter to specify a set of comma delimited V2 contacts ids to cross-referenced with their V3 contact_ids. See Migrating to V3 to learn more.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
sequence_ids
required
string <csv> <= 500 items
Example: sequence_ids=1995998026,1882999944,1775099999

Comma delimited list of V2 API contact ids to cross-reference with the V3 API contact_id value. Endpoint accepts a maximum of 500 ids at a time.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contacts/contact_id_xrefs?sequence_ids=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "xrefs": [
    ]
}

GET SMS Engagement History for a Contact

Use this method to return SMS engagement details for a contact, such as SMS consent and advertising frequency details.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

The contact's unique ID.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/contacts/sms_engagement_history/%7Bcontact_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
[
  • {
    }
]

GET Contact Consent Counts

Use to get the total contacts count for the account and the total contact-consent counts for each consent state. Optionally, to include the total number of contacts that subscribed within the last 30 days in the results, use new_subscribers in the include query parameter. To optimize open rates, reduce spam reports, and help grow your business, you must value your contact's consent to receive or to not receive your emails.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
include
string
Value: "new_subscriber"
Example: include=new_subscriber

Use to return the total number of contacts that subscribed within the last 30 days in the results.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contacts/counts?include=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "total": 72,
  • "explicit": 10,
  • "implicit": 20,
  • "pending": 30,
  • "unsubscribed": 12,
  • "new_subscriber": 1
}

PUT Resubscribe a Contact

Use this endpoint to send a confirmation resubscribe email to a contact in order to get their confirmation to resubscribe. This endpoint also adds the resubscribed contact to the contact lists you specify in the request body. You can only send a resubscribe email to the unsubscribed contact once. The contact is not resubscribed until after you receive their confirmation.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

The ID that uniquely identifies the contact to resubscribe.

Request Body schema: application/json
required

The JSON payload used to specify one (or more) contact lists to which the contact requested to be resubscribed.

list_ids
required
Array of strings <uuid> [ items <uuid > ]

Array of list id values. Constant Contact adds the resubscribed contact to the contact lists you provide in the array.

Responses

Request samples

Content type
application/json
{
  • "list_ids": [
    ]
}

Contact Lists

Endpoints and methods to get, create, delete, and update one or more contact lists.

GET a List

Use this method to get details about a specific contact list (list_id).

User Privileges:
contacts:lists:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
list_id
required
string <uuid>
Example: cbc05bac-6a41-46fa-a063-79961763bf4b

The system generated ID that uniquely identifies a contact list.

query Parameters
include_membership_count
string
Enum: "all" "active"
Example: include_membership_count=all

Returns the total number of contacts per list that meet your selection criteria. Set the include_membership_count to active, to count only active contacts, or all to include all contacts in the count.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_lists/%7Blist_id%7D?include_membership_count=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "list_id": "06526938-56dd-11e9-932a-fa163ea075fa",
  • "name": "Multiple purchases",
  • "description": "List of repeat customers.",
  • "favorite": false,
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-03-03T10:56:29-05:00",
  • "deleted_at": "2016-03-03T10:56:29-05:00",
  • "membership_count": 327
}

PUT (update) a List

Updates an existing contact list resource, specified by list_id

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
list_id
required
string <uuid>
Example: cbc05bac-6a41-46fa-a063-79961763bf4b

Unique ID of the contact list to update

Request Body schema: application/json
required

JSON payload containing updates to the specified contact list

name
required
string <= 255 characters

The name given to the contact list

favorite
boolean
Default: false

Identifies whether or not the account has favorited the contact list.

description
string

Text describing the list.

Responses

Request samples

Content type
application/json
{
  • "name": "Multiple purchases",
  • "favorite": true,
  • "description": "List of repeat customers"
}

Response samples

Content type
application/json
{
  • "list_id": "06526938-56dd-11e9-932a-fa163ea075fa",
  • "name": "Multiple purchases",
  • "description": "List of repeat customers.",
  • "favorite": false,
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-03-03T10:56:29-05:00",
  • "deleted_at": "2016-03-03T10:56:29-05:00"
}

DELETE a List

Deletes the specified contact list and its membership. DELETE List requests are processed asynchronously, and you can track the status of the request by making a GET call to the URI shown in the _links property in the response.

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
list_id
required
string <uuid>
Example: cbc05bac-6a41-46fa-a063-79961763bf4b

Unique ID of the list to delete

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/contact_lists/%7Blist_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "activity_id": "98dae057-958f-4b2f-9ed4-41f109afdc3f",
  • "state": "initialized",
  • "created_at": "2016-03-03T10:53:04-05:00",
  • "updated_at": "2016-03-03T10:56:29-05:00",
  • "percent_done": 1,
  • "activity_errors": [
    ],
  • "_links": {
    }
}

GET Lists Collection

Use this method to return details about all contact lists for the account.

This method does not currently support filtering results using the contact list update date.

User Privileges:
contacts:lists:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
integer [ 1 .. 1000 ]
Default: 50

Use to specify the number of results displayed per page of output, from 1 - 500, default = 50.

include_count
boolean
Default: false
Example: include_count=true

Set include_count to true to return the total number of contact lists that meet your selection criteria.

include_membership_count
string
Enum: "all" "active"
Example: include_membership_count=all

Use to include the total number of contacts per list. Set to active, to count only active (mailable) contacts, or all to count all contacts.

name
string
Example: name=TopTier

Use to get details for a single list by entering the full name of the list.

status
string
Enum: "all" "active" "deleted"
Example: status=all

Use to get lists by status. Accepts comma-separated status values.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_lists?limit=50&include_count=false&include_membership_count=SOME_STRING_VALUE&name=SOME_STRING_VALUE&status=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "lists": [
    ],
  • "lists_count": 249,
  • "_links": {
    }
}

POST (create) a List

Create a new contact list resource

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

JSON payload defining the new contact list

name
required
string <= 255 characters

The name given to the contact list

favorite
boolean
Default: false

Identifies whether or not the account has favorited the contact list.

description
string

Text describing the list.

Responses

Request samples

Content type
application/json
{
  • "name": "Multiple purchases",
  • "favorite": true,
  • "description": "List of repeat customers"
}

Response samples

Content type
application/json
{
  • "list_id": "06526938-56dd-11e9-932a-fa163ea075fa",
  • "name": "Multiple purchases",
  • "description": "List of repeat customers.",
  • "favorite": false,
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-03-03T10:56:29-05:00",
  • "deleted_at": "2016-03-03T10:56:29-05:00"
}

GET a collection of V2 and V3 API List IDs

Use this endpoint to migrate your locally stored V2 contact list data to the new V3 format. Developers are expected to use this endpoint sparingly. This endpoint is NOT intended for regular or repeated use. Constant Contact will eventually deprecate and remove this endpoint.

This GET call retrieves a collection of cross-referenced list sequence IDs (id used in the V2 API) and UUIDs (list_id used in the V3 API). This endpoint is intended for developers who have an existing V2 API integration, and are migrating their users to a new V3 API integration. The V2 and V3 APIs use different resource ID formats. Use the sequence_ids query parameter to specify a set of comma delimited V2 list ids to cross-reference. See Migrating Apps and Data to V3 to learn more."

User Privileges:
contacts:lists:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
sequence_ids
required
string <csv> <= 500 items
Example: sequence_ids=1995998026,1882999944,1775099999

Comma delimited list of V2 API list ids to cross-reference with the V3 API list_id value. Endpoint accepts a maximum of 500 ids at a time.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_lists/list_id_xrefs?sequence_ids=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "xrefs": [
    ]
}

Contact Tags

Endpoints and methods to get, create, delete, and update one or more contact tags.

GET Tag Details

Use this method to get tag details for a specified tag_id. Use the include_count query parameter to include or exclude the total number of contacts to which this tag is assigned. To learn more, see Get a Tag's Details.

User Privileges:
contacts:read
Authorizations:
(oauth2_implicitoauth2_access_code)
path Parameters
tag_id
required
string <uuid>
Example: d938260a-af1e-11e9-a540-fa163e595123

The ID that uniquely identifies a tag (UUID format).

query Parameters
include_count
boolean
Default: false
Example: include_count=true

Use to include (true) or exclude (false) the total number of tagged contacts (contacts_count) from the results.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_tags/%7Btag_id%7D?include_count=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tag_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "name": "Gold card member",
  • "contacts_count": 325,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "tag_source": "ESTY"
}

PUT (Update) a Tag

Use this method to rename an existing tag to a new unique tag name (name). The maximum length is 255 characters. The tag_source value cannot be updated using this method. You can set the tag_source value using the POST contact_tags method. Learn more

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
tag_id
required
string <uuid>
Example: 30c97dd0-332e-11eb-923c-fa163e595327

The system generated ID used to uniquely identify the tag that you want to rename (UUID format).

Request Body schema: application/json
required

The JSON payload used to update the tag name (name).

name
required
string [ 1 .. 255 ] characters

The new tag name to use. The tag name must be unique.

Responses

Request samples

Content type
application/json
{
  • "name": "Bronze card member"
}

Response samples

Content type
application/json
{
  • "tag_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "name": "Gold card member",
  • "contacts_count": 325,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "tag_source": "ESTY"
}

DELETE a Tag

Use this method to create an activity used to un-assign a tag from all assigned contacts and delete the tag. This is an asynchronous activity. To view activity details for the delete request, use the href link returned in the response. Learn more.

User Privileges:
contacts:write
Authorizations:
(oauth2_implicitoauth2_access_code)
path Parameters
tag_id
required
string <uuid>
Example: 30c97dd0-332e-11eb-923c-fa163e595327

The ID that uniquely identifies a tag in UUID format.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/contact_tags/%7Btag_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "activity_id": "d44ac96c-24f3-11eb-8ae8-fa163e595123",
  • "state": "completed",
  • "created_at": "2016-01-23T13:48:44.108Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "percent_done": 25,
  • "activity_errors": [
    ],
  • "status": {
    },
  • "_links": {
    }
}

GET Details for All Tags

Use this endpoint to get details for all tags in your account. Use the include_count query parameter to include the total number of contacts assigned each tag. Use the limit query parameter to limit the number of tag results returned per page. To get the next page of results, copy the cursor={the cursor ID} from the resulting href link and add it (&) to the URL. For example:

/v3/contact_tags?limit=1&cursor=

bGltaXQ9MSZuZXh0PTJjZDgwMjdhLTc4YzAtMTFlOS1iZmQwLWZhMTYzZTZiMDFjMQ=

To learn more, see [Get Tags](/api_guide/tags_get.html).
User Privileges:
contacts:read
Authorizations:
(oauth2_implicitoauth2_access_code)
query Parameters
limit
integer [ 1 .. 500 ] characters
Default: 50
Example: limit=25

Use to specify the number of tag results (up to 500) to display per page of output. The default is 50.

include_count
boolean
Default: false
Example: include_count=true

Returns the total number of contacts (contacts_count) to which a tag applies.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_tags?limit=50&include_count=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tags": [
    ],
  • "_links": {
    }
}

POST (Create) a Tag

Use this method to create a new tag. The tag name is required and must be unique and can include most common keyboard symbols. Optionally, when creating a new tag you can specify the source (tag_source) used to identify the contacts to tag in the request body. Learn more.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload to use to create a new tag.

name
required
string [ 1 .. 255 ] characters

Specify a unique name to use to identify the tag. Tag names must be at least one character in length and not more than 255 characters.

tag_source
string

The source used to identify the contacts to tag.

Responses

Request samples

Content type
application/json
{
  • "name": "Silver card member",
  • "tag_source": "ESTY"
}

Response samples

Content type
application/json
{
  • "tag_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "name": "Gold card member",
  • "contacts_count": 325,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "tag_source": "ESTY"
}

Contacts Reporting

Contact reporting endpoints are used to gather activity reports for campaigns sent to a contact.

GET Contact Activity Details

Gets the tracking activity data for a single contact, sorted in descending activity date order.

You must chose either the `tracking_activities_list` query parameter and or the `tracking_activity_type` query parameter to specify one or more tracking activity types In the request. The `tracking_activities_list` and `tracking_activities_type` query parameters are mutually exclusive.

Valid tracking activity types
em_sendsSend activities
em_opensEmail open tracking activities
em_clicksLink click-through tracking activities
em_bouncesBounce tracking activities
em_optoutsOpt-out tracking activities
em_forwardsForward to a friend tracking activities
p_contact_openLanding page opens
p_contact_clickLanding page clicks
p_contact_addLanding page adds
p_contact_update Landing page updates
User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: aa9ff7b0-478d-11e6-8059-00163e3c8e19

The contact's ID for which tracking activity data is requested.

query Parameters
tracking_activities_list
string <csv>
Example: tracking_activities_list=em_clicks,em_opens

Specify one or more tracking activity types to include as a comma-delimited string. The tracking_activities_list and tracking_activities_type query parameters are mutually exclusive.

tracking_activity_type
Array of strings
Example: tracking_activity_type=`tracking_activity_type=em_sends&tracking_activity_type=em_opens`

Specify one or more tracking activity types to include as an array. The tracking_activities_list and tracking_activities_type query parameters are mutually exclusive.

include_campaign_activity_names
boolean
Default: true
Example: include_campaign_activity_names=true

Default (true) returns campaign activity names in the results. Not including campaign activity names in the results (false), is more efficient.

limit
string [ 1 .. 100 ]
Default: "100"
Example: limit=20

The number of tracking activities to return in a single page. Valid values are 1 to 100. Default is 100.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/contact_reports/%7Bcontact_id%7D/activity_details?tracking_activities_list=SOME_STRING_VALUE&tracking_activity_type=SOME_ARRAY_VALUE&include_campaign_activity_names=true&limit=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET Average Open and Click Rates

Gets the average open and click rate for a given account and contact.

Looks at all tracking activities for bulk emails from a given contact over the given date range. Range cannot exceed 5 years.

Returns the rates and the number of campaign activities that were included in the calculation.

If no activities fall into the given date range, all rates will return 0 and the number of included activities will be 0.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: aa9ff7b0-478d-11e6-8059-00163e3c8e19

The contact id which is requesting tracking activity data (e.g. aa9ff7b0-478d-11e6-8059-00163e3c8e19)

query Parameters
start
required
string

The starting date, in ISO 8601 format, to use to get campaigns. For example: 2019-01-01T00:00:00-0500.

end
required
string

The ending date, in ISO 8601 format, to use to get campaigns. For example: 2019-12-01T00:00:00-0500.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/contact_reports/%7Bcontact_id%7D/open_and_click_rates?start=SOME_STRING_VALUE&end=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "contact_id": "71600990-908b-11e6-907f-00166bff25",
  • "included_activities_count": 10,
  • "average_open_rate": 0.6,
  • "average_click_rate": 0.6
}

GET Contact Action Summary

Get a list of the recent emails (aka, campaign activities) sent to a specific contact and a summary of the actions the contact took on that email for the most recent 200 campaigns.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
contact_id
required
string
Example: aa9ff7b0-478d-11e6-8059-00163e3c8e19

The contact id which is requesting tracking activity data (e.g. aa9ff7b0-478d-11e6-8059-00163e3c8e19)

query Parameters
start
required
string

The starting date, in ISO 8601 format, to use to get campaigns. For example: 2019-01-01T00:00:00-0500.

end
required
string

The ending date, in ISO 8601 format, to use to get campaigns. For example: 2019-12-01T00:00:00-0500.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/contact_reports/%7Bcontact_id%7D/activity_summary?start=SOME_STRING_VALUE&end=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "contact_id": "71600990-908b-11e6-907f-00166bff25",
  • "campaign_activities": [
    ],
  • "_links": {
    }
}

Contacts Custom Fields

Endpoints and methods to get, create, delete, and update on one or more custom fields.

GET a custom_field

This GET call retrieves a custom_field resource, specified by custom_field_id.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
custom_field_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of the custom_field on which to operate.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/contact_custom_fields/%7Bcustom_field_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "label": "Vehicle make and model year",
  • "name": "Vehicle_make_and_model_year",
  • "type": "string",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-03-03T10:53:04-05:00"
}

PUT (update) a custom_field

This PUT request updates an existing custom_field object.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
custom_field_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of the custom_field on which to operate.

Request Body schema: application/json
required

The JSON payload used to update an existing custom field. Any properties omitted in the PUT request are overwritten with a null value.

label
required
string <= 50 characters

The display name for the custom_field shown in the UI as free-form text

type
required
string
Enum: "string" "date"

Specifies the type of value the custom_field field accepts: string or date.

Responses

Request samples

Content type
application/json
{
  • "label": "Vehicle make and model year",
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "label": "Vehicle make and model year",
  • "name": "Vehicle_make_and_model_year",
  • "type": "string",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-03-03T10:53:04-05:00"
}

DELETE a custom_field

This DELETE request deletes a custom_field from the user's account

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
custom_field_id
required
string
Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a

Unique ID of the custom_field on which to operate.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/contact_custom_fields/%7Bcustom_field_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

GET custom_fields Collection

This GET request returns all custom_fields defined in the user's account.

This method does not currently support filtering results using the custom field update date.

User Privileges:
contacts:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
integer [ 1 .. 100 ]
Default: 50

Specifies the number of results displayed per page of output, from 1 - 100, default = 50.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/contact_custom_fields?limit=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "custom_fields": [
    ],
  • "_links": {
    }
}

POST (create) a custom_field

This POST request adds a new custom_field to the user's account. A user can configure up to 100 custom_fields in their account.

User Privileges:
contacts:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The JSON payload required to create a new custom_field

label
required
string <= 50 characters

The display name for the custom_field shown in the UI as free-form text

type
required
string
Enum: "string" "date"

Specifies the type of value the custom_field field accepts: string or date.

Responses

Request samples

Content type
application/json
{
  • "label": "Vehicle make and model year",
  • "type": "string"
}

Response samples

Content type
application/json
{
  • "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
  • "label": "Vehicle make and model year",
  • "name": "Vehicle_make_and_model_year",
  • "type": "string",
  • "updated_at": "2016-01-23T13:48:44.108Z",
  • "created_at": "2016-03-03T10:53:04-05:00"
}

Email Campaigns

Use email campaign endpoints and methods to get, create, and update email campaigns.

GET a Collection of Email Campaigns

Use this method to list and get details about your email campaigns. By default, this method returns all email campaigns for the user account including deleted email campaigns. To get email campaigns within a date-range, use the after_date and before_date query parameters.

This endpoint does not return campaign activity details for each email campaign in the collection. To get email campaign activity details for a single email campaign, use the GET /emails/{campaign_id} endpoint."

This method does not currently support filtering results using the email campaign creation date.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
integer <int32>
Default: 50

Specifies the number of campaigns to display on each page of output that is returned (from return 1 - 500). The default returns 50 campaigns per page.

before_date
string <date-time>
Example: before_date=2021-01-10T11:42:57.000Z

Use to return email campaigns with updated_at timestamps that are before a specific date and time (in ISO-8601 format). Use with the after_date query parameter to get email campaigns sent within a specific date range.

after_date
string <date-time>
Example: after_date=2021-03-10T11:42:57.000Z

Use to return email campaigns with last updated_at timestamps that are after a specific date and time (in ISO-8601 format). Use with the before_date query parameter to get email campaigns sent within a specific date range.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/emails?limit=50&before_date=SOME_STRING_VALUE&after_date=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "_links": {
    },
  • "campaigns": [
    ]
}

POST (Create) a New Email Campaign

Use this method to create a new email campaign. This method also creates new primary_email and permalink email campaign activities and associates them with the new email campaign.

The request body must contain the name property and the email_campaign_activities array. The name must be unique. The email_campaign_activities array contains the main content of your email campaign and must include format_type, from_name, from_email, reply_to_email, subject, and html_content properties. The from_email address you use must use a verified email address for your account. NOTE: If you create an email campaign using a legacy (V7) format, Constant Contact automatically converts it to the newer custom code format.

User Privileges:
campaign:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

A JSON request body that contains the email content.

name
required
string <= 80 characters

The unique and descriptive name that you specify for the email campaign.

required
Array of objects (EmailCampaignActivityInput)

The content of the email campaign as an array that contains a single email campaign activity object.

Responses

Request samples

Content type
application/json
{
  • "name": "December Newsletter for Dog Lovers",
  • "email_campaign_activities": [
    ]
}

Response samples

Content type
application/json
{
  • "campaign_activities": [
    ],
  • "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
  • "created_at": "2018-02-06T22:09:15.000Z",
  • "current_status": "Draft",
  • "name": "December Newsletter for Dog Lovers",
  • "type": "NEWSLETTER",
  • "type_code": 10,
  • "updated_at": "2018-06-27T10:28:09.000Z"
}

GET Details About a Single Email Campaign

Use this method to get details about a single email campaign and campaign related activities. Details include the email campaign name, current status, create date, last update date, and a list of campaign activities; including the campaign_activity_id and role.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The ID (UUID format) that uniquely identifies this email campaign.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/%7Bcampaign_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "campaign_activities": [
    ],
  • "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
  • "created_at": "2018-02-06T22:09:15.000Z",
  • "current_status": "Draft",
  • "name": "December Newsletter for Dog Lovers",
  • "type": "NEWSLETTER",
  • "type_code": 10,
  • "updated_at": "2018-06-27T10:28:09.000Z"
}

DELETE an Email Campaign

Use this method to delete an email campaign and the email campaign activities associated with the email campaign. You cannot delete an email campaign when it has a Scheduled status.

Constant Contact users can restore deleted email campaigns using the UI.

User Privileges:
campaign:delete
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the email campaign you are deleting.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/emails/%7Bcampaign_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PATCH (Update) an Email Campaign Name

Use this method to rename an email campaign. The name is not visible to contacts. The name must be unique and cannot exceed 80 characters. You cannot rename email campaigns that have a Removed status.

User Privileges:
campaign:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique identifier for an email campaign.

Request Body schema: application/json
required

A JSON payload that contains the new email campaign name.

name
required
string <= 80 characters

The updated email campaign name. The email campaign name must be unique.

Responses

Request samples

Content type
application/json
{
  • "name": "December Newsletter for Dog Lovers"
}

Response samples

Content type
application/json
{
  • "campaign_activities": [
    ],
  • "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
  • "created_at": "2018-02-06T22:09:15.000Z",
  • "current_status": "Draft",
  • "name": "December Newsletter for Dog Lovers",
  • "type": "NEWSLETTER",
  • "type_code": 10,
  • "updated_at": "2018-06-27T10:28:09.000Z"
}

GET a Collection of V2 and V3 API Email Campaign Identifiers

Use this endpoint to migrate your locally stored V2 email campaign data to the new V3 format. Developers are expected to use this endpoint sparingly. This endpoint is NOT intended for regular or repeated use. Constant Contact will eventually deprecate and remove this endpoint.

Use this method to migrate your local V2 API email data to the V3 API format. For each value that you provide in the v2_email_campaign_ids query parameter, this method returns the corresponding V3 campaign_id and V3 campaign_activity_id UUID value. For more information on the changes to the email campaign resource model, see V3 Email Campaign Resource Changes in the API guide.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
v2_email_campaign_ids
required
string <csv> <= 50 items
Example: v2_email_campaign_ids=1100567546598,1604567396117,12002485195578

Comma separated list of V2 API campaignId values. You can enter up to 50 V2 campaignId values in each request.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/emails/campaign_id_xrefs?v2_email_campaign_ids=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "xrefs": [
    ]
}

GET a Single Email Campaign Activity

Use this method to return a specific email campaign activity. Each email campaign activity contains the email content, metadata, and styling information of an email. Email campaign activities can also contain either contact lists or segments. Constant Contact uses this information to determine who to send the email campaign activity to when you schedule it. You cannot get email campaign activities that have a REMOVED status.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity.

query Parameters
include
string <csv>
Enum: "physical_address_in_footer" "permalink_url" "html_content" "document_properties"

Use the include query parameter to enter a comma separated list of additional email campaign activity properties for the V3 API to return. Valid values are physical_address_in_footer, permalink_url, html_content, and document_properties.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D?include=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd",
  • "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
  • "role": "primary_email",
  • "contact_list_ids": [
    ],
  • "segment_ids": [
    ],
  • "current_status": "DRAFT",
  • "format_type": 5,
  • "from_email": "jdodge@constantcontact.com",
  • "from_name": "Jake Dodge",
  • "reply_to_email": "jdodge@constantcontact.com",
  • "subject": "Holiday Special Newsletter",
  • "html_content": "<html><body>[[trackingImage]] <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a> </body></html>",
  • "template_id": "1000755366001",
  • "permalink_url": "https://conta.cc/2GaQ8AY",
  • "preheader": "You don't want to miss this.",
  • "physical_address_in_footer": {
    },
  • "document_properties": {
    }
}

PUT (Update) An Email Campaign Activity

Use this method to update an email campaign activity by including the complete email campaign activity with your changes in the request body. The request body requires the from_name, from_email, reply_to_email, and subject properties.

You can only update email campaign activities that have the primary_email role and that are in DRAFT or Done status. When you use a PUT method to update a resource, the V3 API overwrites any properties that are missing in the request body. However, the V3 API does not overwrite subresources that you omit in the request body or missing properties in subresources. This method considers physical_address_in_footer, document_properties, html_content, and permalink_url subresources of the email campaign activity.

User Privileges:
campaign:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the email campaign activity you are updating.

Request Body schema: application/json
required

A request body payload that contains the complete email campaign activity with your changes.

contact_list_ids
Array of strings

The contacts that Constant Contact sends the email campaign activity to as an array of contact list_id values. You cannot use contact lists and segments at the same time in an email campaign activity.

segment_ids
Array of integers

The contacts that Constant Contact sends the email campaign activity to as an array containing a single segment_id value. Only format_type 3, 4, and 5 email campaign activities support segments. You cannot use contact lists and segments at the same time in an email campaign activity.

from_email
required
string

The email "From Email" field for the email campaign activity. You must use a confirmed Constant Contact account email address. Make a GET call to /account/emails to return a collection of account emails and their confirmation status.

from_name
required
string

The email "From Name" field for the email campaign activity.

reply_to_email
required
string

The email "Reply To Email" field for the email campaign activity. You must use a confirmed Constant Contact account email address. Make a GET call to /account/emails to return a collection of account emails and their confirmation status.

subject
required
string

The email "Subject" field for the email campaign activity.

html_content
string

The HTML or XHTML content for the email campaign activity. Only format_type 1 and 5 (legacy custom code emails or modern custom code emails) can contain html_content.

preheader
string

The email preheader for the email campaign activity. Only format_type 3, 4, and 5 email campaign activities use the preheader property.

object (EmailPhysicalAddress)
object

An object that contains optional properties for legacy format type emails (format_type 1 and 2). If you attempt to add a property that does apply to the email format_type, the API will ignore the property.

Responses

Request samples

Content type
application/json
{
  • "contact_list_ids": [
    ],
  • "segment_ids": [
    ],
  • "from_email": "jdodge@constantcontact.com",
  • "from_name": "Jake Dodge",
  • "reply_to_email": "jdodge@constantcontact.com",
  • "subject": "Holiday Special Newsletter",
  • "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": {
    },
  • "document_properties": {
    }
}

Response samples

Content type
application/json
{
  • "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd",
  • "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
  • "role": "primary_email",
  • "contact_list_ids": [
    ],
  • "segment_ids": [
    ],
  • "current_status": "DRAFT",
  • "format_type": 5,
  • "from_email": "jdodge@constantcontact.com",
  • "from_name": "Jake Dodge",
  • "reply_to_email": "jdodge@constantcontact.com",
  • "subject": "Holiday Special Newsletter",
  • "html_content": "<html><body>[[trackingImage]] <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a> </body></html>",
  • "template_id": "1000755366001",
  • "permalink_url": "https://conta.cc/2GaQ8AY",
  • "preheader": "You don't want to miss this.",
  • "physical_address_in_footer": {
    },
  • "document_properties": {
    }
}

GET Details for a Resend to Non-openers Campaign Activity

Get details about a resend to non-openers campaign activity. If resend activity does not exist for the specified campaign_activity_id, an empty list is returned in the results. You can only create one resend activity per email campaign.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/non_opener_resends \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
[
  • {
    }
]

POST a Resend to Non-openers Campaign Activity

Use this POST method to resend a primary campaign activity to contacts that did not open a campaign activity that has a current status of Draft, Scheduled, or Done. You can only create one resend activity per email campaign.

After an email campaign activity is sent to contacts, Constant Contact waits the specified number of delay_days or delay_minutes (properties are mutually exclusive) before resending to non-openers. If you set both delay_days or delay_minutes, delay_minutes is ignored in the request. You can resend to non-openers a minimum of twelve hours (720 minutes) and a maximum of up to 10 days (or 10 x 1440 minutes) after the initial send date.

User Privileges:
campaign:send
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

Request Body schema: application/json
required

A JSON request body that specifies when to resend the campaign activity to non-openers.

resend_subject
required
string

The subject line used when resending the email campaign activity.

delay_days
integer <int32>

The number of days to wait before Constant Contact resends the email. Valid values include 1 to 10 days. This property is mutually exclusive with delay_minutes. This value is only returned in the response results if the resend activity was created with delay_days or the delay_minutes equal to an exact day value.

delay_minutes
integer <int32>

The number of minutes to wait before Constant Contact resends the email campaign activity. There are 1,440 minutes in a day. Valid values includes a minimum of 720 (12 hours) and a maximum of 14,400 minutes (10 days). This property is mutually exclusive with delay_days

Responses

Request samples

Content type
application/json
{
  • "resend_subject": "Our Big Sale is Coming Soon!",
  • "delay_days": 3,
  • "delay_minutes": 1000
}

Response samples

Content type
application/json
{
  • "resend_subject": "Our Big Sale is Coming Soon!",
  • "delay_days": 7,
  • "delay_minutes": "10,080",
  • "resend_date": "2019-08-24T14:15:22Z",
  • "resend_request_id": "DRAFT"
}

DELETE a Resend to Non Openers Activity

Use this DELETE method to delete (unschedule) a resend to non openers activity.

User Privileges:
campaign:send
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

resend_request_id
required
string
Example: 389093

The unique ID associated with the resend for the email campaign activity (for example: 389093). If the email campaign activity is currently in draft status, specify DRAFT as the ID.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/non_opener_resends/%7Bresend_request_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Email Campaigns AB Tests

Use email campaigns A/B Test endpoints and methods to get, create, delete and update A/B tests.

GET A/B Test Details for an Email Campaign Activity

Use this method to get A/B test details for a primary email campaign activity, such as the alternate email subject line, the contact test percentage size, and the number of hours to wait to determine the winning subject line to use. Currently, A/B tests support subject line only.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/abtest \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
  • "test_size": 30,
  • "winner_wait_duration": 24
}

POST (Create) an A/B Test for an Email Campaign Activity

Use this method to create a new A/B test for a primary email campaign activity. You must specify an alternative subject line, the percentage of contact to use for the A/B test, and the number of hours to wait after the A/B test is sent before determining the winning subject line. To create an A/B test, the campaign must have a current_status of DRAFT. When you create an A/B test, the type changes from Newsletter (code= 10) to A/B Test (code= 57).

User Privileges:
campaign:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

Request Body schema: application/json
required

Specify the alternative_subject line, test_size percentage of contacts (value must from 5 to 50 inclusively), and the winner_wait_duration (value must be 6, 12, 24, or 48 hours).

alternative_subject
required
string

The alternate email subject line to use for A/B testing.

test_size
required
integer <int32>

The percentage of contact recipients to participate in the A/B Test. For example, if the value is 30, then 30% of contacts will receive the email campaign with subject line A, and 30% of contacts will receive the email campaign with subject line B. Valid values include 5 to 50 percent. Currently, A/B tests support subject line only.

winner_wait_duration
required
integer <int32>

The number of hours Constant Contact waits after the A/B test is sent before determining the winning subject line. The winner is the subject line with the highest number of contact opens. Valid values include 6, 12, 24, and 48. After the winner is determined, Constant Contact automatically sends the email campaign with the winning subject line to all the remaining contacts, which did not participate in the A/B test.

Responses

Request samples

Content type
application/json
{
  • "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
  • "test_size": 30,
  • "winner_wait_duration": 24
}

Response samples

Content type
application/json
{
  • "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
  • "test_size": 30,
  • "winner_wait_duration": 24
}

DELETE an A/B Test for an Email Campaign Activity

Deletes an A/B Test on an primary email campaign activity. You can only delete A/B tests that have a current_status of Draft. Deleting an A/B tests reverts the email campaign activity type from A/B Test (code= 57) back to NewsLetter (code= 10). Constant Contact uses the original subject line, rather than the alternate A/B test subject line, when an A/B test is deleted.

User Privileges:
campaign:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for the primary email campaign activity.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/abtest \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Email Reporting

Use the email reporting endpoints and methods to get reporting data for email campaigns you sent to contacts.

GET an Email Links Report

Use this method to return link details, including the number of unique contacts that clicked each link in an email campaign activity, and the type of action associated with clicking each link. To include link details for links that were not clicked, set the no_clicks query parameter to true.

You can return reporting data for primary_email and resend role email campaign activities. For more use case information, see Get an Email Links Report in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 8892baf9-970a-4de6-8400-fa4ec461987c

The unique ID for an email campaign activity.

query Parameters
no_clicks
boolean
Default: false
Example: no_clicks=true

Set this query parameter to true to return details for links that were not clicked in the response results.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/links?no_clicks=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "campaign_activity_id": "8892baf9-970a-4de6-8400-fa4ec461987c",
  • "link_click_counts": [
    ]
}

GET an Email Sends Report

Use this method to get each contact that was sent a specific email campaign activity. This sends report includes general contact data such as the date and time that the email campaign activity was sent to a contact's email address, the contact's first and last name, and unique ID. This report lists the most recent activity first. For more use case information, see Get an Sends report for an Email Campaign Activity in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 8892baf9-970a-4de6-8400-fa4ec461987c

The unique ID for an email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/sends?limit=500' \
  --header 'accept: application/json' \
  --header 'x-api-key: REPLACE_KEY_VALUE'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Opens Report

Use this method to get each time a contact opened a specific email campaign activity. This report includes general 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. This report lists the most recent activity first. For more use case information, see Get an Opens report for an Email Campaign Activity in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 8892baf9-970a-4de6-8400-fa4ec461987c

The unique ID for an email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/opens?limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Unique Opens Report

Use this method to get a unique opens report that provides details about the last time that each contact opened the specified email campaign activity. This report includes general 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. This report lists the most recent activity first. For more use case information, see Get an Unique Opens Report for an Email Campaign Activity in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 8892baf9-970a-4de6-8400-fa4ec461987c

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/unique_opens?limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Did Not Opens Report

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. This report lists the most recent activity first. For more use case information, see Get a Did Not Opens Report for an Email Campaign Activity in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 8892baf9-970a-4de6-8400-fa4ec461987c

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/didnotopens?limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Clicks Report

Use this method to get each time a contact clicked a link, the click date and time, and the device type they used. Use the url_id query parameter to get a clicks report for a specific link URL. Clicks report data is sorted with most recent activity listed first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: c8cdf384-15ca-4dcc-9b6f-4c91121fdc23

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
url_id
integer <int64>
Example: url_id=49920742166

The ID that uniquely identifies a single link URL for which you want to get a clicks report.

limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/clicks?url_id=SOME_INTEGER_VALUE&limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Forwards Report

Use this method to get a report listing each time a contact forwarded the email campaign activity using the forwarding link in the email footer. The report includes general contact information, such as the contact's email address and unique ID, and the date and time that the email campaign activity was forwarded. Forwards report data is sorted with the most recent activity listed first. For more use case information, see Get an Email Forwards Report in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/forwards?limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Opt-outs Report

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. Opt-out report data is sorted with the most recent activity listed first. For more use case information, see Get an Email Opt-outs Report in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/optouts?limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Bounces Report

Use this method to get a report listing contact bounce data for the specified email campaign activity. This report lists the most recent bounce data first and includes contact information, such as the contact's email address, unique ID, and the email bounce date and time. Use the bounce_code query parameter to limit the type of bounce data to return.

For more use case information, see Get a Bounces Report for an Email Campaign Activity in the API guide.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>

The ID that uniquely identifies the email campaign activity to use for this report.

query Parameters
bounce_code
Array of strings
Items Enum: "B" "D" "F" "S" "V" "X" "Z"

To return results for a specific bounce code, select the bounce_code from the drop-down list. To return results for multiple codes, repeat the bounce code parameter for each. For example, to return results for bounce codes B and D use bounce_code=B&bounce_code=D.

limit
string [ 1 .. 500 ]
Default: "500"

The number of tracking activities to return on a page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/email_reports/%7Bcampaign_activity_id%7D/tracking/bounces?bounce_code=SOME_ARRAY_VALUE&limit=500' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET an Email Campaigns Summary Report

Use this method to get aggregate email campaign statistics for up to five hundred email campaigns. The response results include the total number of times that each contact uniquely interacted with each tracked campaign activity.

Results are sorted in descending order by the date that the email was last sent (last_sent_date). Use the limit query parameter to limit the number of email campaign summary reports listed on each page.

For more use case information, see "Get an Email Campaign Summary Report"

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
string
Default: "50"
Example: limit=100

Use the limit query parameter to limit the number of email campaign summaries to return on a single page. The default is 50 and the maximum is 500 per page.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/summary_reports/email_campaign_summaries?limit=50' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "bulk_email_campaign_summaries": [
    ],
  • "aggregate_percents": {
    },
  • "_links": {
    }
}

GET an Email Campaign Stats Report

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.

For each campaign_id, this method returns lists that include total counts (stats) for each type of tracked email and relevant campaign-related percentages (percents). It also returns the date and time at which the campaign stats were last refreshed. If any specified campaign_id is invalid, a 404 error response is returned for all campaigns.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_ids
required
string <= 150
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

A comma-separated list of campaign_ids (UUID's).

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/reports/stats/email_campaigns/%7Bcampaign_ids%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "results": [
    ]
}

GET an Email Campaign Activity Stats Report

Use this method to get performance tracking statistics for up to ten email campaign activities. Statistics include the total number of times contacts interacted with your campaigns and how.

For each campaign_activity_id, this method returns the campaign_id, the total counts (stats) for each type of tracked email activity, and the date and time that Constant Contact last refreshed (last_refresh_time) the stats.

When requesting statistics for multiple email campaign activities, if one or more of the campaign_activity_ids do not exist, were deleted, or do not have any stats associated with it, the campaign_activity_ids and error details display under errors. If any single specified campaign_activity_id is invalid (malformed), a 404 error response is returned for all campaign activities.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_ids
required
string <= 10
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

A comma-separated list of campaign_activity_ids (UUID's).

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/reports/stats/email_campaign_activities/%7Bcampaign_activity_ids%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "results": [
    ]
}

Email Scheduling

Use email scheduling endpoints and methods to schedule an email campaign activity, unschedule an email campaign activity, and GET schedule information.

GET an Email Campaign Activity Schedule

Use this method to return the current schedule for an email campaign activity. This schedule contains the date that Constant Contact will send the email campaign activity to contacts. If the email campaign activity is not in SCHEDULED status, this method returns an empty array and a 200 response code.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/schedules \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

POST (Create) an Email Campaign Activity Schedule

Use this method to schedule when Constant Contact will send an email campaign activity to contacts. Use the scheduled_date request body property to enter the ISO-8601 format date that you want Constant Contact to send the email campaign activity on.

Before you schedule an email campaign activity, you must update the email campaign activity and specify which contacts you want Constant Contact to send the email to. When you make a PUT call to update an email campaign activity, use the contact_list_ids or segment_ids array to add contacts.

You can only schedule email campaign activities that have the primary_email role and are in DRAFT, DONE, or ERROR status. When you schedule an email campaign activity in DONE status, Constant Contact does not send the email campaign activity to contacts that already received it. Constant Contact only sends the email campaign activity to any new contacts in the contact lists or segment you use.

User Privileges:
campaign:send
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity. You can only schedule email campaign activities that have the primary_email role.

Request Body schema: application/json
required

A request body payload that contains the date that you want Constant Contact to send your email campaign activity on. Use "0" as the date to have Constant Contact immediately send the email campaign activity.

scheduled_date
required
string <date-time>

The date when Constant Contact will send the email campaign activity to contacts in ISO-8601 format. For example, 2022-05-17 and 2022-05-17T16:37:59.091Z are valid dates. Use "0" as the date to have Constant Contact immediately send the email campaign activity to contacts.

Responses

Request samples

Content type
application/json
{
  • "scheduled_date": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
[
  • {
    }
]

DELETE an Email Campaign Activity Schedule

Use this method to unschedule an email campaign activity by deleting the schedule. You can only unschedule email campaign activities that are in SCHEDULED status. Unscheduling reverts the email campaign activity to the status prior to SCHEDULED.

User Privileges:
campaign:send
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/schedules \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

POST Test Send an Email Campaign Activity

Use this method to send a test email to specific email addresses. Test emails allow you to verify how the email campaign activity will look before you send it to contacts. This method uses the email_addresses array in the request body to determine the recipients of the test email. The test email does not process any dynamic content in the email campaign activity. Dynamic content includes contact and custom field variables.

You can send up to 50 test emails each day. Each recipient you add to the email_addresses array in the request body counts towards this limit. Successfully sending a test email returns a 204 response code without a response body.

User Privileges:
campaign:send
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity. You can only test send email campaign activities that have the primary_email role.

Request Body schema: application/json
required

A JSON request body that contains the recipients of the test email and an optional personal message.

email_addresses
required
Array of strings <= 5 items

The recipients of the test email as an array of email address strings. You can send a test email to up to 5 different email addresses at a time.

personal_message
string

A personal message for the recipients of the test email. Constant Contact displays this message before the email campaign activity content.

Responses

Request samples

Content type
application/json
{
  • "email_addresses": [
    ],
  • "personal_message": "This is a test send of the email campaign activity."
}

GET the HTML Preview of an Email Campaign Activity

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

Custom code emails (format_type 5) use the Constant Contact account owner's contact information to process contact, custom field, and account variables in the preview.

This method returns the HTML preview encoded as a JSON string. You will need to decode the string before you can use it as valid HTML.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/previews \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd",
  • "from_email": "jdodge@constantconatct.com",
  • "from_name": "Jake Dodge",
  • "preheader": "You don't want to miss this.",
  • "preview_html_content": "<html><body> <a href=\\\"http://www.constantcontact.com\\\">Visit ConstantContact.com!</a> </body></html>",
  • "preview_text_content": "Email Content",
  • "reply_to_email": "jdodge@constantcontact.com",
  • "subject": "Informed Daily Digest"
}

GET the Send History of an Email Campaign Activity

Use this method to return the send history of an email campaign activity. This method returns the send history as an array containing an object for each time you sent a specific email campaign activity to contacts.

Each send history object contains the email campaign activity send date, the number of contacts it was sent to, and the contact lists or segments used to send it. Each send history object also includes if the send attempt completed or encountered an error, and the reason why each error occurred. This method returns results in ascending order starting with the first send attempt.

If the email campaign activity has not been sent to contacts, this method returns a 200 response and an empty array.

User Privileges:
campaign:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string
Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04

The unique ID for an email campaign activity. You can return the send history for primary_email and resend role email campaign activities.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/send_history \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
[
  • {
    }
]

Segments

Use segments to target a subset of your contacts that are most likely to engage with a particular campaign.

GET all Segments

Use this method to get a list of all segments associated with the account. You can sort segment results and limit the number of segments that display per page. Deleted segments are excluded from the results. For more use case information, see Get All Segments in the API guide.

User Privileges:
contacts:lists:read
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
string
Default: "1000"
Example: limit=1000

The number of segments to return on a page.

sort_by
string
Default: "date"
Example: sort_by=sort_by=date

Specify the segment sort order to use. Sort by name (sort_by=name) in ascending order, or sort by date (sort_by=date) in descending order with the most recently updated segments listed first.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/segments?limit=1000&sort_by=date' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/json
{
  • "segments": [
    ],
  • "_links": {
    }
}

POST (create) a Segment

Use this method to create a new segment. You create segments to target a subset of your contacts that meet your specific criteria for a marketing campaign. The segment name must be unique. The segment_criteria requires single-string escaped JSON. Constant Contact uses the contact data that you specify in the segment_criteria to evaluate and identify the contacts you want to target. Contact data can be grouped from different data sources, including:

  • tracking: Supports or and and groups.

  • contact: Supports or and and groups.

  • list_membership: Supports or groups.

  • tags: Supports or groups.

If you do not specify list_membership as criteria, Constant Contact evaluates all contacts in your account. To avoid returning a 400 error response, when specifying the segment_criteria do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated.

For more use case information, see the Segments Overview in the API guide.

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
Request Body schema: application/json
required

The segment name and segment_criteria (requires single-string escaped JSON).

name
required
string

The segment's unique descriptive name.

segment_criteria
required
string <= 20000 characters

The segment_criteria specifies the contact data that Constant Contact uses to evaluate and identify contacts that meet your criteria. The segment_criteria must be formatted as single-string escaped JSON. The top-level group type must be add.

Responses

Request samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}"
}

Response samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
  • "segment_id": 14,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "edited_at": "2019-04-25T11:08:00.000Z"
}

GET a Segment's Details

Use this method to get details about a segment, including the segment criteria. If you know the segment_id You can also use this method to get details about a deleted segment. For more use case information, see Get a Segment's Details in the API guide.

User Privileges:
contacts:lists:read
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
segment_id
required
integer <int32>
Example: 14

The system-generated unique ID that identifies a segment.

Responses

Request samples

curl --request GET \
  --url https://api.cc.email/v3/segments/%7Bsegment_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
  • "segment_id": 14,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "edited_at": "2019-04-25T11:08:00.000Z"
}

PUT (update) a Segment

Use this method to update an existing segment's name (name) and/or contact selection criteria (segment_criteria). You must specify both the name and the segment_criteria in the request body, even if you don't plan to update both. The segment's name must be unique and the JSON must be valid (requires single-string escaped JSON). To avoid returning a 400 error response, when specifying the segment_criteria do not request more than 500 email campaigns or a date range greater than 1825 days (5 years) be evaluated. For more use case information, see Update Segment Details in the API guide.

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
segment_id
required
integer <int32>
Example: 14

The system generated ID that uniquely identifies the segment that you want to modify.

Request Body schema: application/json
required

Include both the name and segment_criteria (single-string escaped JSON) in the body request, then make updates to either or both.

name
required
string

The segment's unique descriptive name.

segment_criteria
required
string <= 20000 characters

The segment_criteria specifies the contact data that Constant Contact uses to evaluate and identify contacts that meet your criteria. The segment_criteria must be formatted as single-string escaped JSON. The top-level group type must be add.

Responses

Request samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}"
}

Response samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
  • "segment_id": 14,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "edited_at": "2019-04-25T11:08:00.000Z"
}

DELETE a Segment

Use this method to delete a segment from your account. Before deleting a segment, verify that the segment is not associated with a scheduled campaign.

Deleted segments do not display in the results when using the GET /segments endpoint. If you know the segment_id, you can use the GET /segments/{segment_id} endpoint to view the deleted segment's details. A segment's details are preserved for external reference purposes, such as displaying the segment name in a campaign's history. For more use case information, see Delete a Segment in the API guide.

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
segment_id
required
integer <int32>
Example: 14

The system generated ID that uniquely identifies the segment.

Responses

Request samples

curl --request DELETE \
  --url https://api.cc.email/v3/segments/%7Bsegment_id%7D \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

PATCH (rename) a Segment

Use this method to update an existing segment name with a new unique name in the request body. For more use case information, see Rename a Segment in the API guide.

User Privileges:
contacts:lists:write
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
segment_id
required
integer <int32>
Example: 14

The system generated ID that uniquely identifies the segment that you want to modify.

Request Body schema: application/json
required

Include the existing segment name in the body request, then rename the segment using a unique new name.

name
required
string

The segment's unique descriptive name.

Responses

Request samples

Content type
application/json
{
  • "name": "Contacts who did not open any email campaign within the last 100 days."
}

Response samples

Content type
application/json
{
  • "name": "Re-engage contacts who did not open the last 5 email campaign activities.",
  • "segment_criteria": "{\"version\":\"1.0.0\",\"criteria\":{\"type\":\"and\",\"group\":[{\"source\":\"tracking\",\"field\":\"not_opened\",\"op\":\"contains-any\",\"const_value\":\"last-n-campaigns\",\"param\":\"5\"}]}}",
  • "segment_id": 14,
  • "created_at": "2019-04-25T11:08:00.000Z",
  • "edited_at": "2019-04-25T11:08:00.000Z"
}

Landing Pages Reporting

Use landing pages reporting endpoints and methods to get reporting data about how a contact interacted with a campaign activity.

GET a Unique Contacts Clicks Landing Page Report

Use this method get details about each contact that clicked a link on a landing page campaign activity. Unique contact clicks are identified by both the contact_id and url_id. The same contact may appear more than once in the results, if they clicked more than one link on the landing page. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact click results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to return only contacts that match a contacts full or partial first or last name, or email. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_unique_contact_clicks?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET a Unique Contacts Opens Landing Page Report

Use this method get details about each contact that opens a link on a landing page. Contacts are uniquely identified by contact_id. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact open results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to only include contacts that contain a certain value. This parameter does full and partial matches and applies to the contact first name, last name, and email fields. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_unique_contact_opens?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET a Contacts Opens Landing Page Report

Use this method get contact details for each time a contact opens a link on a landing page. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact open results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to only include contacts that contain a certain value. This parameter does full and partial matches and applies to the contact first name, last name, and email fields. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_contact_opens?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET a Unique Contacts Updates Landing Page Report

Use this method to get contact details for each contact that updated their contact data from a landing page. Contacts are uniquely identified by contact_id. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact open results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to only include contacts that contain a certain value. This parameter does full and partial matches and applies to the contact first name, last name, and email fields. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_unique_contact_updates?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET a Unique Contacts Adds Landing Page Report

Use this method to get details about each contact added to the account from a specified landing page. Contacts are identified by contact_id. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to only include contacts that contain a certain value. This parameter does full and partial matches and applies to the contact first name, last name, and email fields. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_unique_contact_adds?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

GET a Unique Contacts SMS Opt-In Landing Page Report

Use this method get details about unique contacts that click a link on a landing page to opt in to receiving SMS text messages. Contacts are uniquely identified by `contact_id``. The resulting contact data is listed with most recent activity first.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
path Parameters
campaign_activity_id
required
string <uuid>
Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z

The landing page campaign_activity_id (UUID's) to use to get unique contact click results.

query Parameters
limit
string
Default: "50"
Example: limit=100

Use to limit the number of contact tracking activities to return on a single page. The default is 50 and the maximum is 500 per page.

contacts_filter
string
Example: contacts_filter=Jo

Use to filter the results to return only contacts that match a contacts full or partial first or last name, or email. For example: Josie or Jo.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/landing_pages/campaign_details/%7Bcampaign_activity_id%7D/p_unique_contact_sms_optins?limit=50&contacts_filter=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "tracking_activities": [
    ],
  • "_links": {
    }
}

SMS Reporting

Use SMS reporting endpoints and methods to get reporting data about SMS campaigns.

GET an SMS Campaigns Summary Report

Use this method to get SMS campaign summary details, including the total number of times that each contact uniquely interacted with each tracked campaign activity and aggregate tracking statistics. Results are sorted in descending order by the date the SMS was last sent (last_sent_date). The start_at date is required. Use both the start_at and end_at date query parameters to return only SMS campaign summary details that occurred within a specified date range. Use the limit query parameter to limit the number of results returned per page.

User Privileges:
ui:campaign:metrics
Authorizations:
oauth2_implicitoauth2_access_code
query Parameters
limit
string
Default: "50"
Example: limit=15

Use to limit the number of results to return on a single page (from 1 to 50). The default setting is 50.

start_at
required
string
Example: start_at=2023-01-27T21:56:37.011Z

Use to limit the results to include SMS campaign summary details for SMS campaigns sent on or after the required start_at date you specify. ISO 8601 format.

end_at
string
Example: end_at=2024-01-27T21:56:37.011Z

Use to limit the results to include SMS campaign summary details for SMS campaigns sent on or before the end_at date you specify. ISO 8601 format.

Responses

Request samples

curl --request GET \
  --url 'https://api.cc.email/v3/reports/summary_reports/sms_campaign_summaries?limit=50&start_at=SOME_STRING_VALUE&end_at=SOME_STRING_VALUE' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'accept: application/json'

Response samples

Content type
application/json
{
  • "bulk_sms_campaign_summaries": [
    ],
  • "aggregate_percents": {
    },
  • "_links": {
    }
}

Technology Partners

Use partner endpoints to manage client Constant Contact accounts under your partner account.

GET Partner Client Accounts

Get all Constant Contact client accounts managed under your technology partner account. Use the limit query parameter to set the number of accounts to return on each results page. Use the account_type query parameter to filter client account results by type: all (default), managed, or unmanaged. Only technology partners can access partner endpoints and partner endpoints cannot be tested using the API reference tester. For more use case information, see Get all Partner Client Accounts in the API guide.

Authorizations:
(ctctPartnerAuthorizerapi_key)
query Parameters
offset
string

Depending on the limit you specify, the system determines the offset parameter to use (number of records to skip) and includes it in the link used to get the next page of results

limit
string <int32> [ 10 .. 50 ]
Default: "50"
Example: limit=50

The number of client accounts to return on each page of results. The default value is 50. Entering a limit value less than the minimum (10) or greater than the maximum (50) is ignored and the system uses the default values. Depending on the limit you specify, the system determines the offset parameter to use (number of records to skip) and includes it in the link used to get the next page of results.

account_type
string
Default: "all"
Enum: "all" "managed" "unmanaged"
Example: account_type=managed

Filters client account results by account type: all (default), managed, or unmanaged. Excluding the account_type query parameter returns all client accounts for the partner.

Responses

Response samples

Content type
application/json
{
  • "site_owner_list": [
    ],
  • "_links": {
    }
}

POST (create) a Partner Client Account

Use this POST method to create a new Constant Contact client account under your partner account, set up the billing plan for the account, and to add the new client to the default contact list.

Newly created accounts are free trials which give the user up to 60 days to try Constant Contact before buying. Trial accounts have limits depending on the services that are included.

If a field validation error occurs, a 400 response message is returned.

If provisioning does not complete successfully due to unavailable dependencies, such as database or dependent services, a 503 response message is returned. By default, the client account provision data is stored and processed when provisioning becomes available.

If the partner client account has the Single Sign On (SSO) for all users feature enabled, all users in the client account can sign into the account using SSO. This feature must be set up through the Constant Contact Partner team. For feature details, see Configuring Identity Provider Initiated SSO. Some client account features will be supported in future releases.

For more use case information, see Create a new Partner Client Account in the API guide.

Authorizations:
(ctctPartnerAuthorizerapi_key)
Request Body schema: application/json
required

Create a new Constant Contact client account under your partner account. All required properties must be included in the JSON payload request.

contact_email
required
string <= 80 characters

A valid email address to associate with the client account.

contact_phone
string [ 5 .. 25 ] characters

The contact phone number to associate with the client account.

country_code
required
string [ 2 .. 3 ] characters

The two-letter country code (ISO 3166-1 code) that specifies the country in which the client resides.

organization_name
string [ 1 .. 50 ] characters

The name of organization that identifies the client account.

organization_phone
string [ 5 .. 25 ] characters

The organization phone number. To set the organization phone number using the user interface, select My Settings and in the Organization Information section, select Edit Organization Information.

state_code
required
string

The two-letter state code that represents the US state (country_code is US ) or Canadian province (country_code is CA) where the client's organization is physically located. Leave the state_code blank for non-US states and Canadian provinces.

time_zone_id
string

The offical time zone to use to represent the physical location associated with the client account.

website
string

The client's website URL. Specifying the website URL eliminates the need for clients to provide that information. Requires a valid URL starting with http:// or https://.

login_name
required
string [ 6 .. 50 ] characters

A unique login name to associate with the client account. The name must only contain alphanumeric characters and '-', '_', '@','.','+'.

password
string [ 8 .. 80 ] characters

Required if not using Single Sign On (SSO) or external authenticator. The password to associate with the client account. Passwords must be at least 8 characters and no more than 80 characters in length. Passwords can contain alphabetical letters (A-Z) and (a-z), numbers (0-9), special characters (! @ # $ etc.) and spaces. Passwords should not contain any part of your username and cannot be the same as your last password, or be listed on an industry database; we check for easily guessed or compromised passwords. Your new password is not returned in the response payload for security reasons. If using SSO authentication, use idp_provider and idp_provider_id instead of password.

first_name
string [ 2 .. 80 ] characters

The client account owner's first name.

last_name
string [ 2 .. 80 ] characters

The client account owner's last name.

partner_account_id
string <= 80 characters

The unique client account identifier that partners define and use for billing and reporting purposes.

billing_locale
string

The currency to use when billing the client account. Valid values are: en_US (default, US Dollars) or en_GB (British Pounds).

managed_site_owner
boolean

By default, if the client account is setup as a managed account managed_site_owner is automatically set to true and attempting to override the setting with false is ignored. This helps to avoid getting an account into an unknown state.

enable_single_billing
boolean

If a partner account is setup to allow for single billing and the managed_site_owner property is set to true, use this property to enable the single billing feature for the client account. See your account manager for more information.

gdpr_opt_out
boolean

When creating accounts for users who have opted-out of any marketing communications, set the gdpr_opt_out to true so that Constant Contact does not send any marketing communications to the account.

external_id
string <= 255 characters

The ID used to uniquely identify the client account for the external authenticator. Do not use the password property when using an external authenticator.

external_provider
string <= 80 characters

The name of the provider who externally authenticates this customer. For example, PayPal or Yahoo. Do not use the password property when using an external authenticator.

Responses

Request samples

Content type
application/json
{
  • "contact_email": "clients_email@gmail.com",
  • "contact_phone": "588-768-6868",
  • "country_code": "US",
  • "organization_name": "Hanks Fresh Fruit Delivery",
  • "organization_phone": "401-244-1000",
  • "state_code": "MA",
  • "time_zone_id": "US/Eastern",
  • "login_name": "hank_smith",
  • "password": "123456789",
  • "first_name": "Hank",
  • "last_name": "Smith",
  • "partner_account_id": "partner1234",
  • "billing_locale": "en_US.",
  • "managed_site_owner": true,
  • "enable_single_billing": true,
  • "gdpr_opt_out": true,
  • "external_id": "123456789123456789",
  • "external_provider": "Yahoo"
}

Response samples

Content type
application/json
{
  • "encoded_account_id": "a08e1izzh8t9",
  • "provision_uuid": "x9xx2ede-5a58-4e23-8168-25930c5x7bxb"
}

GET Billing Plan Details for a Client Account

Use this GET method to return billing plan details for a client's Constant Contact account. If you are not on the latest billing plan, contact the Constant Contact Partner Team. However, older billing plans and plan_type enum values will continue to be supported. Only technology partners can access partner endpoints and partner endpoints cannot be tested using the API reference tester. For more use case information, see Get Billing Plan Details for a Client Account in the API guide.

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
encoded_account_id
required
string
Example: a07e1lxqqqo0

Specify the client's unique encoded_account_id.

Responses

Response samples

Content type
application/json
{
  • "plan_type": "GOLD",
  • "current_tiers": [
    ],
  • "billing_status": "Open",
  • "billing_day_of_month": 15
}

PUT (update) Billing Plan Details for a Client Account

Use this PUT method to update the type of billing plan to assign to the Constant Contact client account. The type of billing plan determines which Constant Contact product features that the client account can access. The billing plan that you specify in the request body (plan_type) must already exist in the plan group. Attempting to change to a plan that is currently not available within your partner plan group results in a 400 error response code.

When you create a new client account, the plan_type defaults to TRIAL and the billing_day_of_month defaults to null. The billing_day_of_month property is required if a client account is not set up to use single billing. You can change the day of month (billing_day_of_month) in which to bill a client account only when changing the plan_type value from TRIAL to a different plan_type, otherwise the billing_day_of_month value you enter is ignored. You can choose to enter a specific day of the month or accept the default value, which is the day on which the plan_type value changes from a TRIAL plan to a different plan_type. Changing the plan_type from TRIAL to another plan_type automatically changes the billing_status from Trial to Open.

Only technology partners can access partner endpoints and partner endpoints cannot be tested using the API reference tester. If you are not on the latest billing plan, contact the Constant Contact Partner Team. However, older billing plans and plan_type enum values will continue to be supported.

For more use case information, see PUT Billing Plan Details for a Client Account in the API guide.

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
encoded_account_id
required
string
Example: a07e1lxqqqo0

Specify the client's unique encoded_account_id.

Request Body schema: application/json

plan_type: Updates the billing plan assigned to a client account to a different plan_type.

plan_group_id: To update an older plan_type to a current a plan_type, use the plan_group_id parameter to specify the older billing plan_type number.

  • If the specified plan_group_id does not exist under the account's current plan group, the default partner plan group is used.
  • If the specified plan_group_id exists but does not match the account's current plan group, an error is returned.
  • If the plan_group_id parameter is not included in the request, the accounts current plan group is used.

billing_day_of _month: Updates the day of month in which to bill the client account. This property is required if a client account is not set up to use single billing.

plan_type
string
Enum: "TRIAL" "GOLD" "SILVER" "BRONZE"

Use this property to update the client account billing plan to a different billing plan. After changing the plan_type from TRIAL to any other billing plan type, you cannot change it back to TRIAL.

  • TRIAL: A non-billable account with an expiration date that allows clients to try Constant Contact product features.
  • GOLD: A billable client account plan.
  • SILVER: A billable client account plan.
  • BRONZE: A billable client account plan.

plan_group_id
integer <int32>

Updates an existing client account billing plan group to a new billing plan group. If you don't know the plan_group_id to use, contact our API support team.

billing_day_of_month
integer <int32>

This property is required if a client account is not set up to use single billing. You can choose to enter a specific day of the month or accept the default value, which is the day on which the plan_type value changes from a TRIAL plan to a different plan_type. For trial accounts, the value defaults to null. You can only change the billing_day_of_month when changing the plan_type value from TRIAL to a different plan_type, otherwise the value you enter is ignored.

Responses

Request samples

Content type
application/json
{
  • "plan_type": "GOLD",
  • "plan_group_id": 152,
  • "billing_day_of_month": 15
}

Response samples

Content type
application/json
{
  • "plan_type": "GOLD",
  • "current_tiers": [
    ],
  • "billing_status": "Open",
  • "billing_day_of_month": 15
}

PUT Cancel the Billing Plan for a Client Account

Use this PUT method to cancel a client's Constant Contact account. If the specified client account or technology partner account does not exist, the system returns a 404 error response. If the client account exists under a different technology partner account, the system returns a 400 error response.

To get a list of all canceled client accounts ("billing_status": "Canceled"), make a GET call to the /partner/accounts endpoint.

Only technology partners can access partner endpoints and partner endpoints cannot be tested using the API reference tester.

For more use case information, see Cancel the Billing Plan for a Client Account in the API guide."

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
encoded_account_id
required
string
Example: a07e1lxqqqo0

The system generated ID that uniquely identifies the client account.

Request Body schema: application/json

By default, the current date and time is automatically used as the cancellation date. However, you can specify a future date and time to cancel the account (effective_date) in the request body in ISO format. You can also enter the client's cancellation reason (reason_id).

reason_id
integer <int32>
Enum: 1 2 3 11 12 14 21 27 30

Specifies the reason that the client is canceling their Constant Contact account as follows:

  • 1 Cost Too High
  • 2 Using A Competitive Service
  • 3 Not Doing Email Marketing
  • 11 Something Missing Or Not Working
  • 12 Doing It In-House
  • 14 Poor Results
  • 21 Too Difficult To Use
  • 27 Canceled Online by Customer
  • 30 Dissatisfied With Billing Policies

effective_date
string <date-time>

The client account cancellation date and time in ISO-8601 format.

Responses

Request samples

Content type
application/json
{
  • "reason_id": 1,
  • "effective_date": "2020-02-06T22:09:15.000Z"
}

Response samples

Content type
application/json
{
  • "reason_id": 1,
  • "effective_date": "2020-02-06T22:09:15.000Z"
}

POST Send an API request on Behalf of a Client Account

Use this API method to send an API request on behalf of a managed client account in your partnership.

The request body properties you use in this partner API call determine the structure of the API request that Constant Contact sends on behalf of the managed client account. This includes the HTTP url, HTTP method type, request body, request url parameters, request query parameters, and headers that for the request. You can use this /partner/accounts/{encoded_account_id}/account_operations/sync API method to send a request using non-partner v3 API methods.

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
encoded_account_id
required
string
Example: a07e1lxqqqo0

An encoded account id for a managed account in your partnership.

Request Body schema: application/json

A JSON request body that contains the structure of the HTTP request you are instructing Constant Contact to send on behalf of specific managed account in your partnership.

account_operation_url
required
string

The API method path for the request you are sending on behalf of a managed child account. This value should be a V3 API URL without the https://api.cc.email/v3 base url and with any path parameter names included. For example: /emails/activities/{campaign_activity_id}.

account_operation_method
required
string
Enum: "GET" "POST" "PUT" "DELETE" "PATCH"

The http method for the request you are sending on behalf of a managed child account.

account_operation_payload
string

The request payload for the request you are sending on behalf of a managed child account. If you provide a JSON payload using this parameter, make sure that the JSON is string escaped.

Array of objects (QueryParamObject)

An array containing the query parameters for the request you are sending on behalf of a managed child account.

Array of objects (PathParamObject)

An array containing the path parameters for the request you are sending on behalf of a managed child account.

Array of objects (HeadersObject)

An array containing the headers for the request you are sending on behalf of a managed child account.

Responses

Request samples

Content type
application/json
{
  • "account_operation_url": "/contacts/{contact_id}",
  • "account_operation_method": "GET",
  • "account_operation_payload": "",
  • "account_operation_query_parameters": [
    ],
  • "account_operation_path_parameters": [
    ],
  • "account_operation_headers": [
    ]
}

POST a User Under a Partner's SSO-Enabled Client Account

Use this endpoint to create a new user under a partner client account that has the Single Sign On (SSO) for all users feature enabled.

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
encoded_account_id
required
string
Example: a07e1lxqqqo0

The encoded account ID that identifies the partner's client account to which to add the new user.

Request Body schema: application/json
required

The JSON payload used to create a new user under the specified partner's client account. All request body properties are required (first_name, last_name, role_name, contact_email, login_name, external_id, external_provider).

first_name
required
string <= 80 characters

The client account user's first name.

last_name
required
string <= 80 characters

The client account user's last name.

role_name
required
string
Enum: "account_manager" "campaign_creator"

The role (account_manager or campaign_creator) to assign the client account user.

contact_email
required
string <= 80 characters

The unique email address to associate with the new client account user.

login_name
required
string <= 50 characters

The login name to associate with the new client account user.

external_id
required
string <= 255 characters

The unique ID used to identify the client account user to the external authenticator.

external_provider
required
string <= 80 characters

The unique name used to identify the external provider used to authenticate the client account user. For a list of external providers, contact the Constant Contact Partner Team.

Responses

Request samples

Content type
application/json
{
  • "first_name": "Josie",
  • "last_name": "Lang",
  • "role_name": "campaign_creator",
  • "contact_email": "josie.lang@gmail.com",
  • "login_name": "josie.lang",
  • "external_id": "23378234122161121",
  • "external_provider": "Yahoo"
}

Technology Partners Webhooks

Use partner webhooks to subscribe to billing event notifications from Constant Contact.

GET a Collection of Webhook Topic Subscriptions

Use this GET method to return a collection containing your application's webhook subscriptions.

Authorizations:
(ctctPartnerAuthorizerapi_key)

Responses

Response samples

Content type
application/json
[]

GET Webhook Topic Subscription

Use this GET method to return subscription information for a certain topic_id. Possible topic_id values include:

  • 1 - Billing tier upgrade.
  • 2 - Billing tier downgrade.
  • 3 - Account cancelled.
  • 4 - Account disabled.
Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
topic_id
required
string
Example: 1

Identifies a webhook topic.

Responses

Response samples

Content type
application/json
{}

PUT Webhook Topic Subscription

Use this PUT method to subscribe your application to a topic_id or to update the callback URI for an existing subscription. Possible topic_id values include:

  • 1 - Billing tier upgrade.
  • 2 - Billing tier downgrade.
  • 3 - Account cancelled.
  • 4 - Account disabled.

After you subscribe your application, Constant Contact will automatically start sending POST notifications for your chosen topic to your application's callback URI. This is an example of the POST notification request body:

{"url":"https://api.cc.email/v3/partner/accounts/a07e1my9tbw0/plan",
"api_key":"90ed8738-5190-44a3-bc12-c172930db12c",
"event_type":"tier.increase"}

If your application does not return a success response after receiving a notification, Constant Contact will retry sending the POST notification at 1 minute intervals for up to an hour.
Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
topic_id
required
string
Example: 1

Identifies a webhook topic.

Request Body schema: application/json
required

A JSON payload containing a callback URI. Constant Contact uses this callback URI to notify you about your chosen topic.

hook_uri
string

The callback URI you would like to use to receive webhook notifications. Constant Contact will automatically send POST notifications about your chosen topic to this URI.

Responses

Request samples

Content type
application/json

Response samples

Content type
application/json

DELETE Webhook Topic Subscriptions

Use this DELETE method to unsubscribe your application from notifications on a certain topic_id. Possible topic_id values include:

  • 1 - Billing tier upgrade.
  • 2 - Billing tier downgrade.
  • 3 - Account cancelled.
  • 4 - Account disabled.
Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
topic_id
required
string
Example: 1

Identifies a webhook topic.

Responses

POST Test Send Webhook Notification

Use this POST method to validate a webhook subscription by triggering a test notification for your chosen webhook topic_id. Possible topic_id values include:

  • 1 - Billing tier upgrade.
  • 2 - Billing tier downgrade.
  • 3 - Account cancelled.
  • 4 - Account disabled.

After you successfully send this request, Constant Contact will automatically send a POST notification to your chosen topic's callback URI with example data.

Authorizations:
(ctctPartnerAuthorizerapi_key)
path Parameters
topic_id
required
string
Example: 1

Identifies a webhook topic.

Responses

Response samples

Content type
application/json
{}