Maton

Constant Contact

Access the Constant Contact V3 API with managed OAuth authentication. Manage contacts, email campaigns, contact lists, tags, custom fields, segments, bulk operations, and marketing analytics.

Reference

Get Account Summary

GET /constant-contact/v3/account/summary

Response:

{
  "contact_email": "user@example.com",
  "contact_phone": "5551234567",
  "country_code": "us",
  "encoded_account_id": "abc123",
  "first_name": "John",
  "last_name": "Doe",
  "organization_name": "Acme Inc",
  "state_code": "CA",
  "time_zone_id": "US/Eastern"
}

Update Account Summary

PUT /constant-contact/v3/account/summary
Content-Type: application/json

{
  "first_name": "John",
  "last_name": "Doe",
  "organization_name": "Acme Inc",
  "time_zone_id": "US/Eastern"
}

Get Account Emails

Returns confirmed sender email addresses for the account.

GET /constant-contact/v3/account/emails

Response:

[
  {
    "email_id": 1,
    "email_address": "marketing@example.com",
    "roles": ["BILLING", "CONTACT", "DEFAULT_FROM", "REPLY_TO"],
    "confirm_status": "CONFIRMED",
    "confirm_time": "2026-02-05T07:32:49.766+0000",
    "confirm_source_type": "SITE_OWNER"
  }
]

Add Account Email

POST /constant-contact/v3/account/emails
Content-Type: application/json

{
  "email_address": "newsender@example.com"
}

A confirmation email will be sent to the address. The email must be confirmed before it can be used as a sender.

Get User Privileges

GET /constant-contact/v3/account/user/privileges

List Contacts

GET /constant-contact/v3/contacts

Query parameters:

  • status - Filter by status: all, active, deleted, not_set, pending_confirmation, temp_hold, unsubscribed
  • email - Filter by exact email address
  • lists - Filter by list ID(s), comma-separated
  • segment_id - Filter by segment ID
  • tags - Filter by tag ID(s), comma-separated
  • updated_after - ISO-8601 date filter (e.g., 2026-04-01T00:00:00Z)
  • include - Include subresources: custom_fields, list_memberships, taggings, notes (comma-separated)
  • limit - Results per page (default 50, max 500)

Example with filters:

GET /constant-contact/v3/contacts?email=john@example.com&status=all
GET /constant-contact/v3/contacts?updated_after=2026-04-01T00:00:00Z&limit=100
GET /constant-contact/v3/contacts?include=custom_fields,list_memberships,taggings&limit=50

Get Contact

GET /constant-contact/v3/contacts/{contact_id}

Query parameters:

  • include - Include subresources: custom_fields, list_memberships, taggings, notes (comma-separated)

Example:

GET /constant-contact/v3/contacts/{contact_id}?include=custom_fields,list_memberships,taggings,notes

Response:

{
  "contact_id": "uuid",
  "email_address": {
    "address": "john@example.com",
    "permission_to_send": "implicit",
    "created_at": "2026-04-28T21:46:22Z",
    "updated_at": "2026-04-28T21:46:22Z",
    "opt_in_source": "Account",
    "opt_in_date": "2026-04-28T21:46:22Z",
    "confirm_status": "off"
  },
  "first_name": "John",
  "last_name": "Doe",
  "create_source": "Account",
  "created_at": "2026-04-28T21:46:22Z",
  "updated_at": "2026-04-28T21:46:22Z",
  "custom_fields": [],
  "list_memberships": ["list-uuid"],
  "taggings": [],
  "notes": []
}

Create Contact

IMPORTANT: The create_source field is required.

POST /constant-contact/v3/contacts
Content-Type: application/json

{
  "email_address": {
    "address": "john@example.com",
    "permission_to_send": "implicit"
  },
  "first_name": "John",
  "last_name": "Doe",
  "job_title": "Developer",
  "company_name": "Acme Inc",
  "create_source": "Account",
  "list_memberships": ["list-uuid-here"]
}

Valid create_source values: Account, Contact, Landing Page

Update Contact

IMPORTANT: The update_source field is required.

PUT /constant-contact/v3/contacts/{contact_id}
Content-Type: application/json

{
  "email_address": {
    "address": "john@example.com"
  },
  "first_name": "John",
  "last_name": "Smith",
  "update_source": "Account"
}

Valid update_source values: Account, Contact, Landing Page

Delete Contact

DELETE /constant-contact/v3/contacts/{contact_id}

Returns 204 No Content on success.

Create or Update Contact (Sign-Up Form)

Use this endpoint to create a new contact or update an existing one by email address without checking if they exist first:

POST /constant-contact/v3/contacts/sign_up_form
Content-Type: application/json

{
  "email_address": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "list_memberships": ["list-uuid-here"]
}

Response:

{
  "contact_id": "uuid",
  "action": "created"
}

The action field indicates whether the contact was created or updated.

Get Contact Counts

GET /constant-contact/v3/contacts/counts

Response:

{
  "total": 150,
  "explicit": 100,
  "implicit": 40,
  "pending": 5,
  "unsubscribed": 5
}

List Contact Lists

GET /constant-contact/v3/contact_lists

Query parameters:

  • include_count - Include total list count (true/false)
  • include_membership_count - Include contact count per list: all, active, unsubscribed
  • limit - Results per page

Example:

GET /constant-contact/v3/contact_lists?include_membership_count=all

Response:

{
  "lists": [
    {
      "list_id": "uuid",
      "name": "Newsletter Subscribers",
      "description": "Main newsletter",
      "favorite": false,
      "created_at": "2026-02-05T07:19:59Z",
      "updated_at": "2026-02-05T07:19:59Z",
      "membership_count": 150
    }
  ],
  "lists_count": 1
}

Get Contact List

GET /constant-contact/v3/contact_lists/{list_id}

Query parameters:

  • include_membership_count - Include membership count: all, active, unsubscribed

Create Contact List

POST /constant-contact/v3/contact_lists
Content-Type: application/json

{
  "name": "Newsletter Subscribers",
  "description": "Main newsletter list",
  "favorite": false
}

Update Contact List

PUT /constant-contact/v3/contact_lists/{list_id}
Content-Type: application/json

{
  "name": "Updated List Name",
  "description": "Updated description",
  "favorite": true
}

Delete Contact List

DELETE /constant-contact/v3/contact_lists/{list_id}

Returns 202 Accepted (deletion is asynchronous).

List Tags

GET /constant-contact/v3/contact_tags

Query parameters:

  • limit - Results per page

Create Tag

POST /constant-contact/v3/contact_tags
Content-Type: application/json

{
  "name": "VIP Customer"
}

Update Tag

PUT /constant-contact/v3/contact_tags/{tag_id}
Content-Type: application/json

{
  "name": "Premium Customer"
}

Delete Tag

DELETE /constant-contact/v3/contact_tags/{tag_id}

Returns 202 Accepted (deletion is asynchronous).

List Custom Fields

GET /constant-contact/v3/contact_custom_fields

Create Custom Field

POST /constant-contact/v3/contact_custom_fields
Content-Type: application/json

{
  "label": "Customer ID",
  "type": "string"
}

Valid types: string, date

Response:

{
  "custom_field_id": "uuid",
  "label": "Customer ID",
  "name": "customer_id",
  "type": "string",
  "version": 1,
  "created_at": "2026-04-28T21:45:57Z",
  "updated_at": "2026-04-28T21:45:57Z"
}

Delete Custom Field

DELETE /constant-contact/v3/contact_custom_fields/{custom_field_id}

List Email Campaigns

GET /constant-contact/v3/emails

Query parameters:

  • limit - Results per page (default 50)
  • before_date - ISO-8601 date filter
  • after_date - ISO-8601 date filter

Response:

{
  "campaigns": [
    {
      "campaign_id": "uuid",
      "name": "March Newsletter",
      "current_status": "Draft",
      "type": "CUSTOM_CODE_EMAIL",
      "type_code": 26,
      "created_at": "2026-04-28T21:47:35.000Z",
      "updated_at": "2026-04-28T21:47:35.000Z"
    }
  ]
}

Get Email Campaign

GET /constant-contact/v3/emails/{campaign_id}

Response includes campaign activity IDs:

{
  "campaign_activities": [
    {
      "campaign_activity_id": "uuid",
      "role": "primary_email"
    },
    {
      "campaign_activity_id": "uuid",
      "role": "permalink"
    }
  ],
  "campaign_id": "uuid",
  "current_status": "DRAFT",
  "name": "March Newsletter",
  "type": "CUSTOM_CODE_EMAIL"
}

Create Email Campaign

POST /constant-contact/v3/emails
Content-Type: application/json

{
  "name": "March Newsletter",
  "email_campaign_activities": [
    {
      "format_type": 5,
      "from_name": "Company Name",
      "from_email": "marketing@example.com",
      "reply_to_email": "reply@example.com",
      "subject": "March Newsletter",
      "html_content": "<html><body><h1>Hello!</h1></body></html>"
    }
  ]
}

The from_email must be a confirmed account email address (see Account Emails).

Rename Email Campaign

PATCH /constant-contact/v3/emails/{campaign_id}
Content-Type: application/json

{
  "name": "New Campaign Name"
}

Delete Email Campaign

DELETE /constant-contact/v3/emails/{campaign_id}

Returns 204 No Content on success.

Get Campaign Activity

GET /constant-contact/v3/emails/activities/{campaign_activity_id}

Response:

{
  "campaign_activity_id": "uuid",
  "campaign_id": "uuid",
  "role": "primary_email",
  "contact_list_ids": [],
  "segment_ids": [],
  "current_status": "DRAFT",
  "format_type": 5,
  "from_email": "marketing@example.com",
  "from_name": "Company",
  "reply_to_email": "reply@example.com",
  "subject": "Newsletter"
}

Update Campaign Activity

Updates the email content, targeting, and sender information. All fields in the request body are replaced.

PUT /constant-contact/v3/emails/activities/{campaign_activity_id}
Content-Type: application/json

{
  "from_name": "Updated Name",
  "from_email": "marketing@example.com",
  "reply_to_email": "reply@example.com",
  "subject": "Updated Subject",
  "html_content": "<html><body><h1>Updated Content</h1></body></html>",
  "contact_list_ids": ["list-uuid-here"]
}

IMPORTANT: from_email is required in the update body. Omitting it returns a validation error.

Preview Campaign Activity

Returns the rendered HTML and text preview of the email.

GET /constant-contact/v3/emails/activities/{campaign_activity_id}/previews

Response:

{
  "campaign_activity_id": "uuid",
  "from_email": "marketing@example.com",
  "from_name": "Company",
  "preview_html_content": "<html>...</html>",
  "preview_text_content": "Plain text version...",
  "reply_to_email": "reply@example.com",
  "subject": "Newsletter"
}

Send Test Email

Sends a test/proof version of the email to specified addresses.

POST /constant-contact/v3/emails/activities/{campaign_activity_id}/tests
Content-Type: application/json

{
  "email_addresses": ["test@example.com"],
  "personal_message": "Please review this draft"
}

Returns 204 No Content on success.

Schedule Email Campaign

POST /constant-contact/v3/emails/activities/{campaign_activity_id}/schedules
Content-Type: application/json

{
  "scheduled_date": "2026-06-01T10:00:00Z"
}

Note: The campaign activity must have a valid from_email, a physical address on the account, and at least one target list or segment before scheduling.

Get Campaign Schedule

GET /constant-contact/v3/emails/activities/{campaign_activity_id}/schedules

Unschedule Email Campaign

DELETE /constant-contact/v3/emails/activities/{campaign_activity_id}/schedules

Get Non-Opener Resend

GET /constant-contact/v3/emails/activities/{campaign_activity_id}/non_opener_resends

Returns resend details for sent campaigns. Returns empty array if no resend is configured.

Get A/B Test

GET /constant-contact/v3/emails/activities/{campaign_activity_id}/abtest

List Segments

GET /constant-contact/v3/segments

Query parameters:

  • sort_by - Sort field (e.g., name, date)
  • sort_order - asc or desc

Get Segment

GET /constant-contact/v3/segments/{segment_id}

Create Segment

Segments use a criteria object to define the audience filter:

POST /constant-contact/v3/segments
Content-Type: application/json

{
  "name": "Engaged Subscribers",
  "segment_criteria": {
    "version": "3.0.0",
    "criteria": { ... }
  }
}

Note: The segment_criteria must be a JSON object (not a string). The criteria schema is complex and version-dependent. Refer to the Constant Contact Segments Documentation for the full criteria format.

Update Segment

PUT /constant-contact/v3/segments/{segment_id}
Content-Type: application/json

{
  "name": "Updated Segment Name",
  "segment_criteria": { ... }
}

Delete Segment

DELETE /constant-contact/v3/segments/{segment_id}

List Activities

GET /constant-contact/v3/activities

Query parameters:

  • limit - Results per page
  • state - Filter by state: processing, completed, cancelled, failed, timed_out

Get Activity Status

GET /constant-contact/v3/activities/{activity_id}

Response:

{
  "activity_id": "uuid",
  "state": "completed",
  "started_at": "2026-04-28T21:48:16Z",
  "completed_at": "2026-04-28T21:48:16Z",
  "created_at": "2026-04-28T21:48:15Z",
  "updated_at": "2026-04-28T21:48:16Z",
  "percent_done": 100,
  "activity_errors": [],
  "status": {
    "items_total_count": 1,
    "items_completed_count": 1
  }
}

Add Contacts to Lists

POST /constant-contact/v3/activities/add_list_memberships
Content-Type: application/json

{
  "source": {
    "contact_ids": ["contact-uuid-1", "contact-uuid-2"]
  },
  "list_ids": ["list-uuid"]
}

The source can also use list_ids to copy contacts from other lists:

{
  "source": {
    "list_ids": ["source-list-uuid"]
  },
  "list_ids": ["target-list-uuid"]
}

Remove Contacts from Lists

POST /constant-contact/v3/activities/remove_list_memberships
Content-Type: application/json

{
  "source": {
    "contact_ids": ["contact-uuid-1", "contact-uuid-2"]
  },
  "list_ids": ["target-list-uuid"]
}

Add Tags to Contacts

POST /constant-contact/v3/activities/contacts_taggings_add
Content-Type: application/json

{
  "source": {
    "contact_ids": ["contact-uuid-1", "contact-uuid-2"]
  },
  "tag_ids": ["tag-uuid"]
}

Remove Tags from Contacts

POST /constant-contact/v3/activities/contacts_taggings_remove
Content-Type: application/json

{
  "source": {
    "contact_ids": ["contact-uuid-1", "contact-uuid-2"]
  },
  "tag_ids": ["tag-uuid"]
}

Export Contacts

POST /constant-contact/v3/activities/contact_exports
Content-Type: application/json

{
  "contact_ids": ["contact-uuid-1", "contact-uuid-2"],
  "fields": ["first_name", "last_name", "email"]
}

The response includes a results link to download the export:

{
  "activity_id": "uuid",
  "state": "initialized",
  "_links": {
    "self": { "href": "/v3/activities/{activity_id}" },
    "results": { "href": "/v3/contact_exports/{export_id}" }
  }
}

Download Contact Export

After the export activity completes, download the CSV:

GET /constant-contact/v3/contact_exports/{export_id}

Returns CSV data.

Import Contacts

POST /constant-contact/v3/activities/contacts_file_import
Content-Type: multipart/form-data

{file: contacts.csv, list_ids: ["list-uuid"]}

Delete Contacts in Bulk

POST /constant-contact/v3/activities/contact_delete
Content-Type: application/json

{
  "contact_ids": ["contact-uuid-1", "contact-uuid-2"]
}

Email Campaign Summaries

GET /constant-contact/v3/reports/summary_reports/email_campaign_summaries

Response:

{
  "bulk_email_campaign_summaries": [...],
  "aggregate_percents": {
    "click": 5.2,
    "open": 22.1,
    "did_not_open": 72.7,
    "bounce": 1.3,
    "unsubscribe": 0.2
  }
}

Get Email Campaign Report

Returns detailed metrics for a specific sent campaign activity.

GET /constant-contact/v3/reports/email_reports/{campaign_activity_id}

Note: Only available for sent campaigns. Draft campaigns return 404.

Contact Activity Summary

GET /constant-contact/v3/reports/contact_reports/{contact_id}/activity_summary

Response:

{
  "contact_id": "uuid",
  "campaign_activities": [
    {
      "campaign_activity_id": "uuid",
      "sends": 1,
      "opens": 1,
      "clicks": 0,
      "bounces": 0
    }
  ]
}

Resources

PreviousConfluenceNextDropbox

On this page

Reference
Get Account Summary
Update Account Summary
Get Account Emails
Add Account Email
Get User Privileges
List Contacts
Get Contact
Create Contact
Update Contact
Delete Contact
Create or Update Contact (Sign-Up Form)
Get Contact Counts
List Contact Lists
Get Contact List
Create Contact List
Update Contact List
Delete Contact List
List Tags
Create Tag
Update Tag
Delete Tag
List Custom Fields
Create Custom Field
Delete Custom Field
List Email Campaigns
Get Email Campaign
Create Email Campaign
Rename Email Campaign
Delete Email Campaign
Get Campaign Activity
Update Campaign Activity
Preview Campaign Activity
Send Test Email
Schedule Email Campaign
Get Campaign Schedule
Unschedule Email Campaign
Get Non-Opener Resend
Get A/B Test
List Segments
Get Segment
Create Segment
Update Segment
Delete Segment
List Activities
Get Activity Status
Add Contacts to Lists
Remove Contacts from Lists
Add Tags to Contacts
Remove Tags from Contacts
Export Contacts
Download Contact Export
Import Contacts
Delete Contacts in Bulk
Email Campaign Summaries
Get Email Campaign Report
Contact Activity Summary
Resources