Constant Contact

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

Quick Start

# List contacts
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/constant-contact/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/constant-contact/v3/{resource}

The gateway proxies requests to api.cc.email/v3 and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Constant Contact OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=constant-contact&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'constant-contact'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "4314bd0f-fd56-40ab-8c65-2676dd2c23c4",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T07:41:05.859244Z",
    "last_updated_time": "2026-02-07T07:41:32.658230Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "constant-contact",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Constant Contact connections, specify which one to use with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/constant-contact/v3/contacts')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '4314bd0f-fd56-40ab-8c65-2676dd2c23c4')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Account

Get Account Summary

GET /constant-contact/v3/account/summary

Get Account Emails

GET /constant-contact/v3/account/emails

Get User Privileges

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

Contacts

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 email address
• lists - Filter by list ID(s)
• segment_id - Filter by segment ID
• tags - Filter by tag ID(s)
• updated_after - ISO-8601 date filter
• include - Include subresources: custom_fields, list_memberships, taggings, notes
• limit - Results per page (default 50, max 500)

Get Contact

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

Create Contact

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",
  "list_memberships": ["list-uuid-here"]
}

Update Contact

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

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

Delete Contact

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

Create or Update Contact (Sign-Up Form)

Use this endpoint to create a new contact or update an existing one 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"]
}

Get Contact Counts

GET /constant-contact/v3/contacts/counts

Contact Lists

List Contact Lists

GET /constant-contact/v3/contact_lists

Query parameters:

• include_count - Include contact count per list
• include_membership_count - Include membership count
• limit - Results per page

Get Contact List

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

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}

Tags

List Tags

GET /constant-contact/v3/contact_tags

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}

Custom Fields

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"
}

Delete Custom Field

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

Email Campaigns

List Email Campaigns

GET /constant-contact/v3/emails

Query parameters:

• limit - Results per page (default 50)

Get Email Campaign

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

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>"
    }
  ]
}

Update Email Campaign Activity

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

{
  "contact_list_ids": ["list-uuid-here"],
  "from_name": "Updated Name",
  "subject": "Updated Subject"
}

Send Test Email

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

{
  "email_addresses": ["test@example.com"]
}

Schedule Email Campaign

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

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

Segments

List Segments

GET /constant-contact/v3/segments

Get Segment

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

Create Segment

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

{
  "name": "Engaged Subscribers",
  "segment_criteria": "..."
}

Delete Segment

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

Bulk Activities

Import Contacts

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

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

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"]
}

Remove Contacts from Lists

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

{
  "source": {
    "list_ids": ["source-list-uuid"]
  },
  "list_ids": ["target-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"]
}

Get Activity Status

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

List Activities

GET /constant-contact/v3/activities

Reporting

Email Campaign Summaries

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

Query parameters:

• start - Start date (ISO-8601)
• end - End date (ISO-8601)

Get Email Campaign Report

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

Contact Activity Summary

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

Pagination

The API uses cursor-based pagination with a limit parameter:

GET /constant-contact/v3/contacts?limit=50

Response includes pagination links:

{
  "contacts": [...],
  "_links": {
    "next": {
      "href": "/v3/contacts?cursor=abc123"
    }
  }
}

Use the cursor from the next link for subsequent pages:

GET /constant-contact/v3/contacts?cursor=abc123

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/constant-contact/v3/contacts?limit=50',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/constant-contact/v3/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    params={'limit': 50}
)
data = response.json()

Notes

• Resource IDs use UUID format (36 characters with hyphens)
• All dates use ISO-8601 format: YYYY-MM-DDThh:mm:ss.sZ
• Maximum 1,000 contact lists per account
• A contact can belong to up to 50 lists
• Bulk operations are asynchronous - check activity status for completion
• Email campaigns require verified sender email addresses
• format_type: 5 for custom HTML emails
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq or other commands, environment variables like $MATON_API_KEY may not expand correctly in some shell environments

Error Handling

Status	Meaning
400	Missing Constant Contact connection or invalid request
401	Invalid or missing Maton API key, or OAuth token expired
403	Insufficient permissions for the requested operation
404	Resource not found
409	Conflict (e.g., duplicate email address)
429	Rate limited
4xx/5xx	Passthrough error from Constant Contact API

Error Response Format

{
  "error_key": "unauthorized",
  "error_message": "Unauthorized"
}

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Troubleshooting: Invalid App Name

1. Ensure your URL path starts with constant-contact. For example:

• Correct: https://gateway.maton.ai/constant-contact/v3/contacts
• Incorrect: https://gateway.maton.ai/v3/contacts

Resources

• Constant Contact V3 API Overview
• API Reference
• Technical Overview
• Contacts Overview
• Email Campaigns Guide
• Contact Lists Overview
• Maton Community
• Maton Support