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.
curl --request GET \ --url https://api.cc.email/v3/account/user/privileges \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
[- {
- "privilege_id": 30,
- "privilege_name": "campaign:create"
}
]
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.
extra_fields | string <csv> Enum: "physical_address" "company_logo" Example: extra_fields=company_logo Use the |
curl --request GET \ --url 'https://api.cc.email/v3/account/summary?extra_fields=SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "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",
- "physical_address": {
- "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"
}, - "company_logo": {
- "internal_id": "ACCOUNT.IMAGE.5"
}
}
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.
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 |
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. |
{- "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",
}
{- "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",
}
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.
curl --request GET \ --url https://api.cc.email/v3/account/summary/physical_address \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "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"
}
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.
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 |
state_name | string Use if the state where the organization is physically located is not in the United States or Canada. If |
postal_code | string The postal code address (ZIP code) of the organization. This property is required if the |
country_code required | string The two letter ISO 3166-1 code for the organization's country. |
{- "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"
}
{- "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"
}
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.
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 |
state_name | string Use if the state where the organization is physically located is not in the United States or Canada. If |
postal_code | string The postal code address (ZIP code) of the organization. This property is required if the |
country_code required | string The two letter ISO 3166-1 code for the organization's country. |
{- "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"
}
{- "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"
}
Use this method to return a collection of email addresses for the account associated with your access token. When you Create an Email Campaign, you must use an account email address with a CONFIRMED
status in the email campaign from_email
and reply_to_email
headers.
Use the query parameters to filter results. You can filter using confirm_status
, role_code
, or email_address
. For example, searching with confirm_status=CONFIRMED
returns all confirmed email addresses in the account. This method only supports one query parameter at a time.
confirm_status | string Enum: "CONFIRMED" "C" "UNCONFIRMED" "U" Use the |
role_code | string Enum: "CONTACT" "C" "BILLING" "B" "JOURNALING" "J" "REPLY_TO" "R" "OTHER" "O" Use the |
email_address | string Use the |
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'
[- {
- "email_address": "string",
- "email_id": 1,
- "confirm_status": "CONFIRMED",
- "confirm_time": "2019-08-24T14:15:22Z",
- "confirm_source_type": "SITE_OWNER",
- "roles": [
- "CONTACT"
], - "pending_roles": [
- "CONTACT"
]
}
]
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.
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. |
{- "email_address": "dlang@example.com"
}
{- "email_address": "dlang@example.com",
- "email_id": 2,
- "confirm_status": "UNCONFIRMED"
}
Bulk activities endpoints are used to manage large numbers of contacts, lists, and tags.
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.
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. |
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'
{- "activities": [
- {
- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 2200,
- "items_completed_count": 2100,
- "person_count": 8750,
- "error_count": 1,
- "correctable_count": 1,
- "cannot_add_to_list_count": 1,
- "list_count": 3
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}, - "results": {
- "href": "/v3/contacts_exports/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
], - "_links": {
- "next": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
This endpoint returns an activity status report.
activity_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a The unique ID of the activity to GET |
curl --request GET \ --url https://api.cc.email/v3/activities/%7Bactivity_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: 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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 2200,
- "items_completed_count": 2100,
- "person_count": 8750,
- "error_count": 1,
- "correctable_count": 1,
- "cannot_add_to_list_count": 1,
- "list_count": 3
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}, - "results": {
- "href": "/v3/contacts_exports/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
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 with |
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 |
tag_ids | Array of strings <uuid> <= 50 items [ items <uuid > ] Exports contacts assigned one or more of the tags ( |
new_subscriber | boolean Set to |
segment_id | integer Specify the |
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 |
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 |
object |
{- "contact_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "tag_ids": [
- "3fa85f64-5717-4562-b3fc-2c963f66afa6"
], - "new_subscriber": true,
- "segment_id": 12,
- "fields": [
- "email_address"
], - "status": "unsubscribed",
- "exclude": {
- "contact_ids": [
- "4d88f172-21d1-11ea-b5ae-fa163e56c9b0"
]
}
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 8751,
- "items_completed_count": 351
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}, - "results": {
- "href": "/v3/contacts_exports/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
Use this endpoint to retrieve (GET) a CSV file containing exported contacts by providing the activity_id
of a completed CSV export activity.
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. |
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'
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.
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 |
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": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "list_count": 4,
- "items_total_count": 375,
- "items_completed_count": 351
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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_number
s 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.
file required | string <binary> The CSV file you are importing must include either If adding an You can also use custom fields as column headings. Enter the custom field name prefixed with |
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 |
sms_permission_to_send | string Enum: "not_set" "explicit" If importing contact |
curl --request POST \ --url https://api.cc.email/v3/activities/contacts_file_import \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: multipart/form-data'
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 87,
- "person_count": 20,
- "error_count": 1,
- "correctable_count": 1,
- "cannot_add_to_list_count": 1
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
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 |
sms_permission_to_send | string Enum: "explicit" "not_set" Specifies if the contact gave |
{- "import_data": [
- {
- "email": "joe.jones@example.com",
- "first_name": "Joe",
- "last_name": "Jones",
- "job_title": "Chief Innovation Officer",
- "company_name": "RelativeGravity, Inc.",
- "birthday_month": 11,
- "birthday_day": 24,
- "anniversary": "2006-11-15",
- "phone": "555-555-5555",
- "home_phone": "555-555-5555",
- "work_phone": "555-555-4444",
- "mobile_phone": "555-555-3333",
- "other_phone": "555-555-2222",
- "street": "123 Maple Lane",
- "street2": "Apt. 337",
- "city": "Chicago",
- "state": "Illinois",
- "zip": "60609",
- "country": "United States",
- "home_street": "123 Maple Lane",
- "home_street2": "Apt. 337",
- "home_city": "Chicago",
- "home_state": "Illinois",
- "home_zip": "60609",
- "home country": "United States",
- "work_street": "123 Maple Lane",
- "work_street2": "Apt. 337",
- "work_city": "Chicago",
- "work_state": "Illinois",
- "work_zip": "60609",
- "work_country": "United States",
- "other_street": "123 Maple Lane",
- "other_street2": "Apt. 337",
- "other_city": "Chicago",
- "other_state": "Illinois",
- "other_zip": "60609",
- "other_country": "Canada",
- "cf:custom_field_name": "Tesla S 2017",
- "sms_number": "5081231235",
- "sms_consent_date": "07-03-2024"
}
], - "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "sms_permission_to_send": "explicit"
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 87,
- "person_count": 20,
- "error_count": 1,
- "correctable_count": 1,
- "cannot_add_to_list_count": 1
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
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 |
{- "source": {
- "list_ids": [ ],
- "contact_ids": [ ],
- "all_active_contacts": true,
- "engagement_level": "high",
- "tag_ids": [ ]
}, - "exclude": {
- "contact_ids": [
- "4d88f172-21d1-11ea-b5ae-fa163e56c9b0"
]
}, - "list_ids": [ ]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 2200,
- "items_completed_count": 652,
- "list_count": 3
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
The JSON payload used to create the 'add contacts to lists' activity
required | object The |
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. |
{- "source": {
- "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "all_active_contacts": true,
- "contact_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
], - "tag_ids": [ ],
- "engagement_level": "high",
- "segment_id": 12
}, - "exclude": {
- "contact_ids": [
- "4d88f172-21d1-11ea-b5ae-fa163e56c9b0"
]
}, - "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 2200,
- "items_completed_count": 652,
- "list_count": 3
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
Use this endpoint to delete up to 100 contact lists in an account.
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_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "list_count": 5
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fa57a7-cf55-4185-cc1a-58ed29bf0a6a"
}
}
}
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
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 | |
tag_ids required | Array of strings <uuid> <= 50 items [ items <uuid > ] An array of tags ( |
{- "source": {
- "contact_ids": [
- "358f6a5e-21f6-11ea-a1cb-fa163e56c9b0"
], - "list_ids": [
- "6eeb4756-1cf5-11ea-859f-fa163e56c9b0"
], - "tag_ids": [
- "c6915956-fde3-4081-977e-c3b8d1b068a7"
], - "all_active_contacts": false,
- "new_subscriber": true
}, - "exclude": {
- "contact_ids": [
- "c7172ca0-f353-11e8-aff2-fa163e56c9b0"
]
}, - "tag_ids": [
- "5bbf758c-d8ce-11e9-8d3a-fa163e56c9b0"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 100,
- "items_completed_count": 25
}, - "_links": {
- "self": {
- "href": "string"
}, - "results": {
- "href": "string"
}
}
}
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
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 | |
tag_ids required | Array of strings <uuid> <= 50 items [ items <uuid > ] An array of tags ( |
{- "source": {
- "contact_ids": [
- "358f6a5e-21f6-11ea-a1cb-fa163e56c9b0"
], - "list_ids": [
- "6eeb4756-1cf5-11ea-859f-fa163e56c9b0"
], - "tag_ids": [
- "c6915956-fde3-4081-977e-c3b8d1b068a7"
], - "all_active_contacts": false,
- "new_subscriber": true
}, - "exclude": {
- "contact_ids": [
- "c7172ca0-f353-11e8-aff2-fa163e56c9b0"
]
}, - "tag_ids": [
- "5bbf758c-d8ce-11e9-8d3a-fa163e56c9b0"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 100,
- "items_completed_count": 25
}, - "_links": {
- "self": {
- "href": "string"
}, - "results": {
- "href": "string"
}
}
}
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.
An array of string values (tag_id
s) to delete.
tag_ids required | Array of strings <uuid> <= 500 items [ items <uuid > ] The tag IDs ( |
{- "tag_ids": [
- "00e4429c-3beb-11eb-9f34-fa163e56c9b9"
]
}
{- "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": [
- "Message describing the error condition."
], - "status": {
- "items_total_count": 100,
- "items_completed_count": 25
}, - "_links": {
- "self": {
- "href": "string"
}, - "results": {
- "href": "string"
}
}
}
Use this endpoint to delete up to 100 custom fields for an account.
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. |
{- "custom_field_ids": [ ]
}
{- "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": [
- "Message describing the error condition."
], - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
contact_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of contact to GET |
include | string <csv> Enum: "custom_fields" "list_memberships" "phone_numbers" "street_addresses" "taggings" "notes" Example: include=custom_fields,list_memberships Use |
curl --request GET \ --url 'https://api.cc.email/v3/contacts/%7Bcontact_id%7D?include=SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "opt_in_source": "Contact",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_source": "Contact",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "opt_out_reason": "I am no longer interested in this service.",
- "confirm_status": "confirmed"
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number_id": "6eec28a6-1cf5-11ea-859f-fa163e56c9b0",
- "phone_number": "+1-555-555-5555",
- "kind": "home",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "update_source": "Account",
- "create_source": "Account"
}
], - "street_addresses": [
- {
- "street_address_id": "977a9a2e-3e00-11ea-804b-fa163e56c9b0",
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
- "sms_address": "7815551212",
- "dial_code": "1",
- "country_code": "US",
- "update_source": "Contact",
- "create_source": "Account",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "advertised_frequency": "1",
- "advertised_interval": "monthly",
- "created_at": "2016-01-23T13:48:44.108Z",
- "updated_at": "2016-01-23T13:48:44.108Z"
}
]
}
}
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.
contact_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of contact to update |
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 | integer Accepts values from 1-31; must be used with |
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 |
Array of objects (ContactCustomField) <= 25 items Array of up to 25 | |
Array of objects (PhoneNumberPut) <= 3 items Array of up to 3 | |
Array of objects (StreetAddressPut) <= 3 items Array of up to 3 | |
list_memberships | Array of strings <uuid> <= 50 items [ items <uuid > ] Array of up to 50 |
taggings | Array of strings <uuid> <= 50 items [ items <uuid > ] Array of tags ( |
Array of objects (Note) <= 150 items An array of notes about the contact listed by most recent note first. | |
object (ContactSmsChannel) |
{- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit",
- "opt_out_reason": "I am no longer interested in this service."
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number": "+1-555-555-5555",
- "kind": "home"
}
], - "street_addresses": [
- {
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "full_sms_address": "17815551212",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}
{- "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "opt_in_source": "Contact",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_source": "Contact",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "opt_out_reason": "I am no longer interested in this service.",
- "confirm_status": "confirmed"
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number_id": "6eec28a6-1cf5-11ea-859f-fa163e56c9b0",
- "phone_number": "+1-555-555-5555",
- "kind": "home",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "update_source": "Account",
- "create_source": "Account"
}
], - "street_addresses": [
- {
- "street_address_id": "977a9a2e-3e00-11ea-804b-fa163e56c9b0",
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
- "sms_address": "7815551212",
- "dial_code": "1",
- "country_code": "US",
- "update_source": "Contact",
- "create_source": "Account",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "advertised_frequency": "1",
- "advertised_interval": "monthly",
- "created_at": "2016-01-23T13:48:44.108Z",
- "updated_at": "2016-01-23T13:48:44.108Z"
}
]
}
}
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.
contact_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of contact to DELETE |
curl --request DELETE \ --url https://api.cc.email/v3/contacts/%7Bcontact_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: application/json'
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.
status | string <csv> Enum: "all" "active" "deleted" "not_set" "pending_confirmation" "temp_hold" "unsubscribed" Use the |
string Example: email=xyz@example.com Use the | |
lists | string <= 25 Example: lists=04fe9a-a579-43c5-bb1a-58ed29bf0a6a,04fe9a-a579-43c5-bb1a-58ed29bf0a6a,04fe9a-a579-43c5-bb1a-58ed29bf0a6a Use the |
segment_id | string <= 1 Example: segment_id=14 Use to get contacts that meet the segment criteria for a single specified |
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 |
updated_after | string <date-time> Example: updated_after=2022-01-01T16:37:59.091Z Use |
updated_before | string <date-time> Example: updated_before=2022-07-16T16:37:59.091Z Use |
created_after | string <date-time> Example: created_after=2021-01-01T16:37:59.091Z Use |
created_before | string <date-time> Example: created_before=2022-07-16T16:37:59.091Z Use |
optout_after | string <date-time> Example: optout_after=2022-11-16T16:20:59.091Z Use |
optout_before | string <date-time> Example: optout_before=2022-11-16T16:20:59.091Z Use |
include | string <csv> Enum: "custom_fields" "list_memberships" "phone_numbers" "street_addresses" "taggings" "notes" Example: include=custom_fields,list_memberships Use |
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: |
include_count | boolean Example: include_count=true Set |
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. |
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'
{- "contacts": [
- {
- "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "opt_in_source": "Contact",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_source": "Contact",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "opt_out_reason": "I am no longer interested in this service.",
- "confirm_status": "confirmed"
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number_id": "6eec28a6-1cf5-11ea-859f-fa163e56c9b0",
- "phone_number": "+1-555-555-5555",
- "kind": "home",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "update_source": "Account",
- "create_source": "Account"
}
], - "street_addresses": [
- {
- "street_address_id": "977a9a2e-3e00-11ea-804b-fa163e56c9b0",
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
- "sms_address": "7815551212",
- "dial_code": "1",
- "country_code": "US",
- "update_source": "Contact",
- "create_source": "Account",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "advertised_frequency": "1",
- "advertised_interval": "monthly",
- "created_at": "2016-01-23T13:48:44.108Z",
- "updated_at": "2016-01-23T13:48:44.108Z"
}
]
}
}
], - "contacts_count": 3249,
- "_links": {
- "next": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}, - "status": "processing"
}
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.
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 |
birthday_month | integer The month value for the contact's birthday. Valid values are from 1 through 12. The |
birthday_day | integer The day value for the contact's birthday. Valid values are from 1 through 31. The |
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 | |
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 |
taggings | Array of strings <uuid> <= 50 items [ items <uuid > ] Array of tags ( |
Array of objects (Note) <= 150 items An array of notes about the contact. | |
object (ContactSmsChannel) |
{- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit"
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number": "+1-555-555-5555",
- "kind": "home"
}
], - "street_addresses": [
- {
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "00e4429c-3beb-11eb-9f34-fa163e56c9b9"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "full_sms_address": "17815551212",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "consent_medium_details": "IPhone 13 device used to provide consent."
}
]
}
}
{- "contact_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "email_address": {
- "address": "dlang@example.com",
- "permission_to_send": "implicit",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "opt_in_source": "Contact",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_source": "Contact",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "opt_out_reason": "I am no longer interested in this service.",
- "confirm_status": "confirmed"
}, - "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": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "phone_numbers": [
- {
- "phone_number_id": "6eec28a6-1cf5-11ea-859f-fa163e56c9b0",
- "phone_number": "+1-555-555-5555",
- "kind": "home",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00",
- "update_source": "Account",
- "create_source": "Account"
}
], - "street_addresses": [
- {
- "street_address_id": "977a9a2e-3e00-11ea-804b-fa163e56c9b0",
- "kind": "home",
- "street": "123 Kashmir Valley Road",
- "city": "Chicago",
- "state": "Illinois",
- "postal_code": "60609",
- "country": "United States",
- "created_at": "2016-03-03T10:53:04-05:00",
- "updated_at": "2016-03-03T10:56:29-05:00"
}
], - "list_memberships": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "taggings": [
- "e7ddac60-51da-11eb-b3a4-fa163e6b01c1"
], - "notes": [
- {
- "note_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
- "created_at": "2021-05-12T13:48:44.108Z",
- "content": "This contact resubscribed on 2021-05-12."
}
], - "sms_channel": {
- "sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
- "sms_address": "7815551212",
- "dial_code": "1",
- "country_code": "US",
- "update_source": "Contact",
- "create_source": "Account",
- "sms_channel_consents": [
- {
- "sms_consent_permission": "explicit",
- "consent_type": "promotional_sms",
- "opt_in_date": "2016-01-23T13:48:44.108Z",
- "opt_out_date": "2016-01-23T13:48:44.108Z",
- "advertised_frequency": "1",
- "advertised_interval": "monthly",
- "created_at": "2016-01-23T13:48:44.108Z",
- "updated_at": "2016-01-23T13:48:44.108Z"
}
]
}
}
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.
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.
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 |
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_day | integer The day value for the contact's birthday. Valid values are from 1 through 31. The |
object | |
sms_channel | string The contact's SMS compatible phone number. |
{- "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": [
- "07936f78-662a-11eb-af0a-fa163e56c9b0"
], - "custom_fields": [
- {
- "custom_field_id": "1618ae62-4752-11e9-9c8a-fa163e6b01c1",
- "value": "Tesla S 2017"
}
], - "anniversary": "11-15-2006",
- "birthday_month": 11,
- "birthday_day": 24,
- "street_address": {
- "kind": "home",
- "street": "1601 Trapelo Rd",
- "city": "Waltham",
- "state": "Massachusetts",
- "postal_code": "02451",
- "country": "United States"
}, - "sms_channel": "string"
}
{- "contact_id": "ab7ab702-b935-11e9-8a58-fa163e6b01c1",
- "action": "created"
}
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.
sequence_ids required | string <csv> <= 500 items Example: sequence_ids=1995998026,1882999944,1775099999 Comma delimited list of V2 API contact |
curl --request GET \ --url 'https://api.cc.email/v3/contacts/contact_id_xrefs?sequence_ids=SOME_STRING_VALUE' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "xrefs": [
- {
- "sequence_id": "0016633325",
- "contact_id": "ab7ab702-b935-11e9-8a58-fa163e6b01c1"
}
]
}
Use this method to return SMS engagement details for a contact, such as SMS consent and advertising frequency details.
contact_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a The contact's unique ID. |
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'
[- {
- "contact_id": "7f7923da-ebf7-11ec-ae6e-3e22fbb230ec",
- "sms_channel_id": "3fa85f64-5712-6245-b3fc-2c963f66bfc6",
- "sms_channel_history_id": "04515cb3-17be-41e4-823a-f71c3d381c7b",
- "insert_time": "2016-03-03T10:53:04-05:00",
- "history_details": {
- "state": "O",
- "source": "A",
- "consent_type": "promotional_sms",
- "consent_action_time": "2023-01-23 06:09:23 -0800",
- "consent_action_type": "opt_out",
- "consent_medium_type": "MD",
- "source_consent_timestamp": "2016-03-03T10:53:04-05:0",
- "source_sms_number": "6035550239",
- "advertised_frequency": 2,
- "advertised_interval": "W"
}
}
]
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.
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. |
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'
{- "total": 72,
- "explicit": 10,
- "implicit": 20,
- "pending": 30,
- "unsubscribed": 12,
- "new_subscriber": 1
}
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.
contact_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a The ID that uniquely identifies the contact to resubscribe. |
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. |
{- "list_ids": [
- "04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
]
}
Use this method to get details about a specific contact list (list_id
).
list_id required | string <uuid> Example: cbc05bac-6a41-46fa-a063-79961763bf4b The system generated ID that uniquely identifies a contact list. |
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 |
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'
{- "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
}
Updates an existing contact list resource, specified by list_id
list_id required | string <uuid> Example: cbc05bac-6a41-46fa-a063-79961763bf4b Unique ID of the contact list to update |
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. |
{- "name": "Multiple purchases",
- "favorite": true,
- "description": "List of repeat customers"
}
{- "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"
}
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.
list_id required | string <uuid> Example: cbc05bac-6a41-46fa-a063-79961763bf4b Unique ID of the list to delete |
curl --request DELETE \ --url https://api.cc.email/v3/contact_lists/%7Blist_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: 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": [
- "Message describing the error condition."
], - "_links": {
- "self": {
- "href": "/v3/activities/04fa57a7-cf55-4185-cc1a-58ed29bf0a6a"
}
}
}
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.
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_membership_count | string Enum: "all" "active" Example: include_membership_count=all Use to include the total number of contacts per list. Set to |
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. |
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'
{- "lists": [
- {
- "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
}
], - "lists_count": 249,
- "_links": {
- "next": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
Create a new contact list resource
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. |
{- "name": "Multiple purchases",
- "favorite": true,
- "description": "List of repeat customers"
}
{- "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"
}
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."
sequence_ids required | string <csv> <= 500 items Example: sequence_ids=1995998026,1882999944,1775099999 Comma delimited list of V2 API list |
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'
{- "xrefs": [
- {
- "sequence_id": "0016633325",
- "list_id": "71600990-908b-11e6-907f-1200166bff25"
}
]
}
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.
tag_id required | string <uuid> Example: d938260a-af1e-11e9-a540-fa163e595123 The ID that uniquely identifies a tag (UUID format). |
include_count | boolean Default: false Example: include_count=true Use to include ( |
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'
{- "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"
}
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
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). |
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. |
{- "name": "Bronze card member"
}
{- "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"
}
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.
tag_id required | string <uuid> Example: 30c97dd0-332e-11eb-923c-fa163e595327 The ID that uniquely identifies a tag in UUID format. |
curl --request DELETE \ --url https://api.cc.email/v3/contact_tags/%7Btag_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: 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": [
- {
- "message": "string"
}
], - "status": {
- "items_total_count": 89,
- "items_completed_count": 89
}, - "_links": {
- "self": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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=
limit | integer [ 1 .. 500 ] characters Default: 50 Example: limit=25 Use to specify the number of tag results (up to |
include_count | boolean Default: false Example: include_count=true Returns the total number of contacts ( |
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'
{- "tags": [
- {
- "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"
}
], - "_links": {
- "next": {
- "href": "string",
- "next": {
- "href": "string"
}
}
}
}
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.
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. |
{- "name": "Silver card member",
- "tag_source": "ESTY"
}
{- "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"
}
Contact reporting endpoints are used to gather activity reports for campaigns sent to a contact.
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_sends | Send activities |
em_opens | Email open tracking activities |
em_clicks | Link click-through tracking activities |
em_bounces | Bounce tracking activities |
em_optouts | Opt-out tracking activities |
em_forwards | Forward to a friend tracking activities |
p_contact_open | Landing page opens |
p_contact_click | Landing page clicks |
p_contact_add | Landing page adds |
p_contact_update | Landing page updates |
contact_id required | string Example: aa9ff7b0-478d-11e6-8059-00163e3c8e19 The contact's ID for which tracking activity data is requested. |
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_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 |
include_campaign_activity_names | boolean Default: true Example: include_campaign_activity_names=true Default ( |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "71600990-908b-11e6-907f-00166bff25",
- "campaign_activity_id": "010a0-1234-5678-9012-1100a0c1ab2a",
- "created_time": "2017-04-02T04:08:00.000Z",
- "tracking_activity_type": "em_sends",
- "campaign_activity_name": "April DLCV Newsletter"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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) |
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. |
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'
{- "contact_id": "71600990-908b-11e6-907f-00166bff25",
- "included_activities_count": 10,
- "average_open_rate": 0.6,
- "average_click_rate": 0.6
}
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.
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) |
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. |
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'
{- "contact_id": "71600990-908b-11e6-907f-00166bff25",
- "campaign_activities": [
- {
- "campaign_activity_id": "a3e1fc9a-2bb5-4bd5-a6ad-067ef7d7b818",
- "start_on": "2019-08-24T14:15:22Z",
- "em_bounces": 0,
- "em_clicks": 0,
- "em_forwards": 0,
- "em_opens": 0,
- "em_sends": 0,
- "em_unsubscribes": 0
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
Endpoints and methods to get, create, delete, and update on one or more custom fields.
This GET call retrieves a custom_field
resource, specified by custom_field_id
.
custom_field_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of the |
curl --request GET \ --url https://api.cc.email/v3/contact_custom_fields/%7Bcustom_field_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "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"
}
This PUT request updates an existing custom_field
object.
custom_field_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of the |
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. |
{- "label": "Vehicle make and model year",
- "type": "string"
}
{- "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"
}
This DELETE request deletes a custom_field from the user's account
custom_field_id required | string Example: 04fe9a-a579-43c5-bb1a-58ed29bf0a6a Unique ID of the custom_field on which to operate. |
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'
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.
limit | integer [ 1 .. 100 ] Default: 50 Specifies the number of results displayed per page of output, from 1 - 100, default = 50. |
curl --request GET \ --url 'https://api.cc.email/v3/contact_custom_fields?limit=50' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "custom_fields": [
- {
- "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"
}
], - "_links": {
- "next": {
- "href": "/v3/activities/04fe9a97-a579-43c5-bb1a-58ed29bf0a6a"
}
}
}
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.
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. |
{- "label": "Vehicle make and model year",
- "type": "string"
}
{- "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"
}
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.
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 |
after_date | string <date-time> Example: after_date=2021-03-10T11:42:57.000Z Use to return email campaigns with last |
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'
{- "_links": {
- "next": {
- "href": "string"
}
}, - "campaigns": [
- {
- "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"
}
]
}
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.
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. |
{- "name": "December Newsletter for Dog Lovers",
- "email_campaign_activities": [
- {
- "format_type": 5,
- "from_name": "Jake Dodge",
- "from_email": "jdodge@constantcontact.com",
- "reply_to_email": "jdodge@constantconatct.com",
- "subject": "Informed Daily Digest",
- "preheader": "You don't want to miss this.",
- "html_content": "<html><body>[[trackingImage]] <a href=\"http://www.constantcontact.com\">Visit ConstantContact.com!</a> </body></html>",
- "physical_address_in_footer": {
- "address_line1": "123 Maple Street",
- "address_line2": "Unit 1",
- "address_line3": "string",
- "address_optional": "Near Boston Fire Station",
- "city": "Boston",
- "country_code": "US",
- "organization_name": "Jake Dodge's Pancakes",
- "postal_code": "02451",
- "state_code": "MA",
- "state_non_us_name": "Victoria"
}
}
]
}
{- "campaign_activities": [
- {
- "campaign_activity_id": "0e3feddd-c8da-4d53-a507-aae5082b8b75",
- "role": "primary_email"
}
], - "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"
}
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
.
campaign_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The ID (UUID format) that uniquely identifies this email campaign. |
curl --request GET \ --url https://api.cc.email/v3/emails/%7Bcampaign_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: application/json'
{- "campaign_activities": [
- {
- "campaign_activity_id": "0e3feddd-c8da-4d53-a507-aae5082b8b75",
- "role": "primary_email"
}
], - "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"
}
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.
campaign_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the email campaign you are deleting. |
curl --request DELETE \ --url https://api.cc.email/v3/emails/%7Bcampaign_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
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.
campaign_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique identifier for an email campaign. |
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. |
{- "name": "December Newsletter for Dog Lovers"
}
{- "campaign_activities": [
- {
- "campaign_activity_id": "0e3feddd-c8da-4d53-a507-aae5082b8b75",
- "role": "primary_email"
}
], - "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"
}
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.
v2_email_campaign_ids required | string <csv> <= 50 items Example: v2_email_campaign_ids=1100567546598,1604567396117,12002485195578 Comma separated list of V2 API |
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'
{- "xrefs": [
- {
- "v2_email_campaign_id": "1100567546598",
- "campaign_id": "e4cf53f0-e37f-11e8-9f32-f2801f1b9fd1",
- "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd"
}
]
}
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for an email campaign activity. |
include | string <csv> Enum: "physical_address_in_footer" "permalink_url" "html_content" "document_properties" Use the |
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'
{- "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd",
- "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
- "role": "primary_email",
- "contact_list_ids": [
- "da10f460-3072-11e9-b282-fa163e6b01c1"
], - "segment_ids": [
- 1
], - "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",
- "preheader": "You don't want to miss this.",
- "physical_address_in_footer": {
- "address_line1": "123 Maple Street",
- "address_line2": "Unit 1",
- "address_line3": "string",
- "address_optional": "Near Boston Fire Station",
- "city": "Boston",
- "country_code": "US",
- "country_name": "United States",
- "organization_name": "Jake Dodge's Pancakes",
- "postal_code": "02451",
- "state_code": "MA",
- "state_name": "string",
- "state_non_us_name": "Victoria"
}, - "document_properties": {
- "style_content": ".white{color: #ffffff;}",
- "letter_format": "XHTML",
- "greeting_salutation": "Dear",
- "greeting_name_type": "F",
- "greeting_secondary": "Greetings!",
- "subscribe_link_enabled": "false",
- "subscribe_link_name": "Subscribe to my email list!",
- "text_content": "<Text><Greeting/></Text>",
- "permission_reminder_enabled": "false",
- "permission_reminder": "Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.",
- "view_as_webpage_enabled": "false",
- "view_as_webpage_text": "Having trouble viewing this email?",
- "view_as_webpage_link_name": "Click here to view this email as a web page",
- "forward_email_link_enabled": "true",
- "forward_email_link_name": "Forward email"
}
}
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the email campaign activity you are updating. |
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 |
segment_ids | Array of integers The contacts that Constant Contact sends the email campaign activity to as an array containing a single |
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 |
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 |
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 |
preheader | string The email preheader for the email campaign activity. Only |
object (EmailPhysicalAddress) | |
object An object that contains optional properties for legacy format type emails ( |
{- "contact_list_ids": [
- "da10f460-3072-11e9-b282-fa163e6b01c1"
], - "segment_ids": [
- 1
], - "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": {
- "address_line1": "123 Maple Street",
- "address_line2": "Unit 1",
- "address_line3": "string",
- "address_optional": "Near Boston Fire Station",
- "city": "Boston",
- "country_code": "US",
- "organization_name": "Jake Dodge's Pancakes",
- "postal_code": "02451",
- "state_code": "MA",
- "state_non_us_name": "Victoria"
}, - "document_properties": {
- "style_content": ".white{color: #ffffff;}",
- "greeting_salutation": "Dear",
- "greeting_name_type": "F",
- "greeting_secondary": "Greetings!",
- "subscribe_link_enabled": "false",
- "subscribe_link_name": "Subscribe to my email list!",
- "text_content": "<Text><Greeting/></Text>",
- "permission_reminder_enabled": "false",
- "permission_reminder": "Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.",
- "view_as_webpage_enabled": "false",
- "view_as_webpage_text": "Having trouble viewing this email?",
- "view_as_webpage_link_name": "Click here to view this email as a web page",
- "forward_email_link_enabled": "true",
- "forward_email_link_name": "Forward email"
}
}
{- "campaign_activity_id": "4c08372c-957a-48b5-bc45-72c7f00796cd",
- "campaign_id": "8987dc1a-48ef-433a-b836-7ca4f9aa3481",
- "role": "primary_email",
- "contact_list_ids": [
- "da10f460-3072-11e9-b282-fa163e6b01c1"
], - "segment_ids": [
- 1
], - "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",
- "preheader": "You don't want to miss this.",
- "physical_address_in_footer": {
- "address_line1": "123 Maple Street",
- "address_line2": "Unit 1",
- "address_line3": "string",
- "address_optional": "Near Boston Fire Station",
- "city": "Boston",
- "country_code": "US",
- "country_name": "United States",
- "organization_name": "Jake Dodge's Pancakes",
- "postal_code": "02451",
- "state_code": "MA",
- "state_name": "string",
- "state_non_us_name": "Victoria"
}, - "document_properties": {
- "style_content": ".white{color: #ffffff;}",
- "letter_format": "XHTML",
- "greeting_salutation": "Dear",
- "greeting_name_type": "F",
- "greeting_secondary": "Greetings!",
- "subscribe_link_enabled": "false",
- "subscribe_link_name": "Subscribe to my email list!",
- "text_content": "<Text><Greeting/></Text>",
- "permission_reminder_enabled": "false",
- "permission_reminder": "Hi, just a reminder that you're receiving this email because you have expressed an interest in our company.",
- "view_as_webpage_enabled": "false",
- "view_as_webpage_text": "Having trouble viewing this email?",
- "view_as_webpage_link_name": "Click here to view this email as a web page",
- "forward_email_link_enabled": "true",
- "forward_email_link_name": "Forward email"
}
}
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the primary email campaign activity. |
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'
[- {
- "resend_subject": "Our Big Sale is Coming Soon!",
- "delay_days": 3,
- "delay_minutes": 1000,
- "resend_date": "2019-08-24T14:15:22Z",
- "resend_request_id": "DRAFT",
- "resend_status": "DRAFT"
}
]
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the primary email campaign activity. |
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 |
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 |
{- "resend_subject": "Our Big Sale is Coming Soon!",
- "delay_days": 3,
- "delay_minutes": 1000
}
{- "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"
}
Use this DELETE
method to delete (unschedule) a resend to non openers activity.
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: |
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'
Use email campaigns A/B Test endpoints and methods to get, create, delete and update A/B tests.
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the primary email campaign activity. |
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'
{- "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
- "test_size": 30,
- "winner_wait_duration": 24
}
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
).
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the primary email campaign activity. |
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 |
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 |
{- "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
- "test_size": 30,
- "winner_wait_duration": 24
}
{- "alternative_subject": "Reminder: Our Biggest Sale of the Year is Coming Soon!",
- "test_size": 30,
- "winner_wait_duration": 24
}
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.
campaign_activity_id required | string Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for the primary email campaign activity. |
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'
Use the email reporting endpoints and methods to get reporting data for email campaigns you sent to contacts.
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.
campaign_activity_id required | string <uuid> Example: 8892baf9-970a-4de6-8400-fa4ec461987c The unique ID for an email campaign activity. |
no_clicks | boolean Default: false Example: no_clicks=true Set this query parameter to |
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'
{- "campaign_activity_id": "8892baf9-970a-4de6-8400-fa4ec461987c",
- "link_click_counts": [
- {
- "url_id": "1100577727321",
- "unique_clicks": 99,
- "list_action": "add",
- "list_id": "3377aefd-970a-4de6-8400-ab4ec491624c",
- "link_tag": "google-link-1"
}
]
}
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.
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. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_sends",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2019-04-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_opens",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "computer",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_opens",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "computer",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_didnotopens",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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. |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_clicks",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "computer",
- "url_id": "1100407204171",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> The ID that uniquely identifies the email campaign activity to use for this report. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_forwards",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> The ID that uniquely identifies the email campaign activity to use for this report. |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_optouts",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "opt_out_reason": "The content is not what I expected",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> The ID that uniquely identifies the email campaign activity to use for this report. |
bounce_code | Array of strings Items Enum: "B" "D" "F" "S" "V" "X" "Z" To return results for a specific bounce code, select the |
limit | string [ 1 .. 500 ] Default: "500" The number of tracking activities to return on a page. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "em_bounces",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "bounce_code": "B",
- "current_email_address": "maddie_brown@yahoo.com",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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"
limit | string Default: "50" Example: limit=100 Use the |
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'
{- "bulk_email_campaign_summaries": [
- {
- "campaign_id": "82ee2c37-c8f8-4974-9560-ef93ad51d58z",
- "campaign_type": "Newsletter",
- "last_sent_date": "2019-04-25T11:08:00.000Z",
- "unique_counts": {
- "sends": 3129,
- "opens": 1672,
- "clicks": 256,
- "forwards": 21,
- "optouts": 3,
- "abuse": 1,
- "bounces": 210,
- "not_opened": 1211
}
}
], - "aggregate_percents": {
- "click": 43,
- "open": 12,
- "did_not_open": 23,
- "bounce": 21,
- "unsubscribe": 2
}, - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_ids required | string <= 150 Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z A comma-separated list of |
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'
{- "errors": [
- {
- "error_key": "reportingsvc.not_found.invalid_path_param.campaign_ids.",
- "error_message": "Could not find any campaign stats for all requested campaigns."
}
], - "results": [
- {
- "campaign_id": "82ee2c37-c8f8-4974-9560-ef93ad51d58z",
- "stats": {
- "em_bounces": 10,
- "em_clicks": 280,
- "em_clicks_all": 387,
- "em_clicks_all_computer": 123,
- "em_clicks_all_mobile": 211,
- "em_clicks_all_tablet": 85,
- "em_clicks_all_other": 4,
- "em_clicks_all_none": 2,
- "em_forwards": 39,
- "em_not_opened": 25,
- "em_opens": 220,
- "em_opens_all": 399,
- "em_opens_all_computer": 65,
- "em_opens_all_mobile": 270,
- "em_opens_all_tablet": 199,
- "em_opens_all_other": 10,
- "em_opens_all_none": 2,
- "em_optouts": 2,
- "em_sends": 308
}, - "percents": {
- "bounce": 0,
- "click": 40,
- "desktop_click": 10,
- "desktop_open": 20,
- "did_not_open": 30,
- "mobile_click": 40,
- "mobile_open": 10,
- "open": 70,
- "unsubscribe": 0
}, - "last_refresh_time": "2015-08-25T22:00:09.908Z"
}
]
}
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.
campaign_activity_ids required | string <= 10 Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z A comma-separated list of |
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'
{- "errors": [
- {
- "error_key": "reportingsvc.not_found.invalid_path_param.campaign_ids.",
- "error_message": "Could not find any campaign stats for all requested campaigns."
}
], - "results": [
- {
- "campaign_id": "string",
- "campaign_activity_id": "string",
- "stats": {
- "em_bounces": 10,
- "em_clicks": 280,
- "em_clicks_all": 387,
- "em_clicks_all_computer": 123,
- "em_clicks_all_mobile": 211,
- "em_clicks_all_tablet": 85,
- "em_clicks_all_other": 4,
- "em_clicks_all_none": 2,
- "em_forwards": 39,
- "em_not_opened": 25,
- "em_opens": 220,
- "em_opens_all": 399,
- "em_opens_all_computer": 65,
- "em_opens_all_mobile": 270,
- "em_opens_all_tablet": 199,
- "em_opens_all_other": 10,
- "em_opens_all_none": 2,
- "em_optouts": 2,
- "em_sends": 308,
- "em_abuse": 1,
- "em_bounces_blocked": 1,
- "em_bounces_mailbox_full": 2,
- "em_bounces_nonexistent_address": 3,
- "em_bounces_other": 2,
- "em_bounces_suspended": 1,
- "em_bounces_undeliverable": 19,
- "em_bounces_vacation": 2
}, - "last_refresh_time": "string"
}
]
}
Use email scheduling endpoints and methods to schedule an email campaign activity, unschedule an email campaign activity, and GET schedule information.
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.
campaign_activity_id required | string <uuid> Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for an email campaign activity. |
curl --request GET \ --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/schedules \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
[- {
- "scheduled_date": "2019-08-24T14:15:22Z"
}
]
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.
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 |
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, |
{- "scheduled_date": "2019-08-24T14:15:22Z"
}
[- {
- "scheduled_date": "2019-08-24T14:15:22Z"
}
]
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
.
campaign_activity_id required | string <uuid> Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for an email campaign activity. |
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'
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.
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 |
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. |
{- "email_addresses": [
- "dlang@example.com"
], - "personal_message": "This is a test send of the 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.
campaign_activity_id required | string <uuid> Example: 91569d46-00e4-4a4d-9a4c-d17d98740d04 The unique ID for an email campaign activity. |
curl --request GET \ --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/previews \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "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"
}
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.
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 |
curl --request GET \ --url https://api.cc.email/v3/emails/activities/%7Bcampaign_activity_id%7D/send_history \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
[- {
- "send_id": 1,
- "contact_list_ids": [
- "72876990-b664-11e5-844a-00163e0cb6a5"
], - "segment_ids": [
- 57
], - "count": 200,
- "run_date": "2018-06-27T10:28:09.000Z",
- "send_status": "COMPLETED",
- "reason_code": 0
}
]
Use segments to target a subset of your contacts that are most likely to engage with a particular campaign.
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.
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 ( |
curl --request GET \ --url 'https://api.cc.email/v3/segments?limit=1000&sort_by=date' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "segments": [
- {
- "name": "Re-engage contacts who did not open the last 5 campaigns.",
- "segment_id": 14,
- "created_at": "2019-04-25T11:08:00.000Z",
- "edited_at": "2019-04-25T11:08:00.000Z"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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 |
{- "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\"}]}}"
}
{- "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"
}
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.
segment_id required | integer <int32> Example: 14 The system-generated unique ID that identifies a segment. |
curl --request GET \ --url https://api.cc.email/v3/segments/%7Bsegment_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'accept: 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"
}
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.
segment_id required | integer <int32> Example: 14 The system generated ID that uniquely identifies the segment that you want to modify. |
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 |
{- "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\"}]}}"
}
{- "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"
}
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.
segment_id required | integer <int32> Example: 14 The system generated ID that uniquely identifies the segment. |
curl --request DELETE \ --url https://api.cc.email/v3/segments/%7Bsegment_id%7D \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
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.
segment_id required | integer <int32> Example: 14 The system generated ID that uniquely identifies the segment that you want to modify. |
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. |
{- "name": "Contacts who did not open any email campaign within the last 100 days."
}
{- "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"
}
Use landing pages reporting endpoints and methods to get reporting data about how a contact interacted with a campaign activity.
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_click",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "tablet",
- "url_id": "1100407204171",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_opens",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "tablet",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_opens",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "device_type": "tablet",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_updates",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_adds",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
campaign_activity_id required | string <uuid> Example: 82ee2c37-c8f8-4974-9560-ef93ad51d58z The landing page |
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 |
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. |
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'
{- "tracking_activities": [
- {
- "contact_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_activity_id": "98edac88-f4bc-408c-9e64-acd890384231",
- "tracking_activity_type": "p_contact_sms_optins",
- "email_address": "maddieb@gmail.com",
- "first_name": "Maddie",
- "last_name": "Brown",
- "created_time": "2019-04-25T11:08:00.000Z",
- "deleted_at": "2015-08-10",
- "sms_channel": {
- "country_code": "US",
- "state": "N",
- "formatted_international": "+1 234-555-6789",
- "formatted_national": "(234) 555-6789"
}
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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 |
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 |
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'
{- "bulk_sms_campaign_summaries": [
- {
- "campaign_id": "a2fdc285-f4bc-408c-9e64-f3f89038ec82",
- "campaign_name": "Spring Clearance Sale",
- "last_sent_date": "2019-04-25T11:08:00.000Z",
- "unique_counts": {
- "sends": 100,
- "delivers": 100,
- "opens": 75,
- "clicks": 294,
- "optouts": 0
}, - "campaign_type": "SMS"
}
], - "aggregate_percents": {
- "deliver": 23,
- "click": 43,
- "bounce": 0,
- "unsubscribe": 0
}, - "_links": {
- "next": {
- "href": "string"
}
}
}
Use partner endpoints to manage client Constant Contact accounts under your partner account.
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.
offset | string Depending on the |
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 |
account_type | string Default: "all" Enum: "all" "managed" "unmanaged" Example: account_type=managed Filters client account results by account type: |
{- "site_owner_list": [
- {
- "encoded_account_id": "a08e1izvh8t9",
- "subscriber_count": 65,
- "organization_name": "Zenomatic",
- "site_owner_name": "Zen1016153",
- "billing_status": "Open",
- "last_login_date": "2019-04-25T11:08:00.000Z"
}
], - "_links": {
- "next": {
- "href": "string"
}
}
}
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.
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 ( |
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 |
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: |
managed_site_owner | boolean By default, if the client account is setup as a managed account |
enable_single_billing | boolean If a partner account is setup to allow for single billing and the |
gdpr_opt_out | boolean When creating accounts for users who have opted-out of any marketing communications, set the |
external_id | string <= 255 characters The ID used to uniquely identify the client account for the external authenticator. Do not use the |
external_provider | string <= 80 characters The name of the provider who externally authenticates this customer. For example, PayPal or Yahoo. Do not use the |
{- "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"
}
{- "encoded_account_id": "a08e1izzh8t9",
- "provision_uuid": "x9xx2ede-5a58-4e23-8168-25930c5x7bxb"
}
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.
encoded_account_id required | string Example: a07e1lxqqqo0 Specify the client's unique |
{- "plan_type": "GOLD",
- "current_tiers": [
- {
- "usage_type": "CONTACTS",
- "current_usage": 10,
- "tier": 1,
- "tier_min": 0,
- "tier_max": 500,
- "price": 20,
- "currency_code": "USD"
}
], - "billing_status": "Open",
- "billing_day_of_month": 15
}
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.
encoded_account_id required | string Example: a07e1lxqqqo0 Specify the client's unique |
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.
plan_group_id
does not exist under the account's current plan group, the default partner plan group is used.plan_group_id
exists but does not match the account's current plan group, an error is returned.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_group_id | integer <int32> Updates an existing client account billing plan group to a new billing plan group. If you don't know the |
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": "GOLD",
- "plan_group_id": 152,
- "billing_day_of_month": 15
}
{- "plan_type": "GOLD",
- "current_tiers": [
- {
- "usage_type": "CONTACTS",
- "current_usage": 10,
- "tier": 1,
- "tier_min": 0,
- "tier_max": 500,
- "price": 20,
- "currency_code": "USD"
}
], - "billing_status": "Open",
- "billing_day_of_month": 15
}
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."
encoded_account_id required | string Example: a07e1lxqqqo0 The system generated ID that uniquely identifies the client account. |
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:
|
effective_date | string <date-time> The client account cancellation date and time in ISO-8601 format. |
{- "reason_id": 1,
- "effective_date": "2020-02-06T22:09:15.000Z"
}
{- "reason_id": 1,
- "effective_date": "2020-02-06T22:09:15.000Z"
}
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.
encoded_account_id required | string Example: a07e1lxqqqo0 An encoded account id for a managed account in your partnership. |
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: |
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. |
{- "account_operation_url": "/contacts/{contact_id}",
- "account_operation_method": "GET",
- "account_operation_payload": "",
- "account_operation_query_parameters": [
- {
- "query_param_key": "include",
- "query_param_value": "list_memberships"
}
], - "account_operation_path_parameters": [
- {
- "path_param_key": "contact_id",
- "path_param_value": "04fe9a-a579-43c5-bb1a-58ed29bf0a6a"
}
], - "account_operation_headers": [
- {
- "header_key": "Accept",
- "header_value": "application/json"
}
]
}
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.
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. |
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 ( |
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. |
{- "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"
}
Use partner webhooks to subscribe to billing event notifications from Constant Contact.
Use this GET method to return a collection containing your application's webhook subscriptions.
[- {
- "topic_id": 2,
- "topic_name": "Billing Tier Downgrade",
- "topic_description": "Executes when an account's billing tier is downgraded."
}
]
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.topic_id required | string Example: 1 Identifies a webhook topic. |
{- "topic_id": 2,
- "topic_name": "Billing Tier Downgrade",
- "topic_description": "Executes when an account's billing tier is downgraded."
}
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"}
topic_id required | string Example: 1 Identifies a webhook topic. |
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. |
{
}
{- "topic_id": 1,
}
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.topic_id required | string Example: 1 Identifies a webhook topic. |
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.
topic_id required | string Example: 1 Identifies a webhook topic. |
{- "topic_id": 2,
- "topic_name": "Billing Tier Downgrade",
- "topic_description": "Executes when an account's billing tier is downgraded."
}