Mailchimp

Access the Mailchimp Marketing API with managed OAuth authentication. Manage audiences, campaigns, templates, automations, reports, and subscribers for email marketing.

Quick Start

bash

# List all audiences
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists')
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

code

https://gateway.maton.ai/mailchimp/{native-api-path}

Replace {native-api-path} with the actual Mailchimp API endpoint path (e.g., 3.0/lists). The gateway proxies requests to your Mailchimp data center and automatically injects your OAuth token.

Authentication

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

code

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

bash

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

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

Connection Management

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

List Connections

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=mailchimp&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

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'mailchimp'}).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

bash

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:

json

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "mailchimp",
    "metadata": {}
  }
}

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

Delete Connection

bash

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 Mailchimp connections, specify which one to use with the Maton-Connection header:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API Reference

Lists (Audiences)

Within the Mailchimp app, "audience" is the common term, but the API uses "lists" for endpoints.

Get All Lists

bash

GET /mailchimp/3.0/lists

Query parameters:

•count - Number of records to return (default 10, max 1000)
•offset - Number of records to skip (for pagination)
•fields - Comma-separated list of fields to include
•exclude_fields - Comma-separated list of fields to exclude

Example:

bash

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

Response:

json

{
  "lists": [
    {
      "id": "abc123def4",
      "name": "Newsletter Subscribers",
      "contact": {
        "company": "Acme Corp",
        "address1": "123 Main St"
      },
      "stats": {
        "member_count": 5000,
        "unsubscribe_count": 100,
        "open_rate": 0.25
      }
    }
  ],
  "total_items": 1
}

Get a List

bash

GET /mailchimp/3.0/lists/{list_id}

Example:

bash

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

Create a List

bash

POST /mailchimp/3.0/lists
Content-Type: application/json

{
  "name": "Newsletter",
  "contact": {
    "company": "Acme Corp",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "permission_reminder": "You signed up for our newsletter",
  "campaign_defaults": {
    "from_name": "Acme Corp",
    "from_email": "newsletter@acme.com",
    "subject": "",
    "language": "en"
  },
  "email_type_option": true
}

Update a List

bash

PATCH /mailchimp/3.0/lists/{list_id}

Delete a List

bash

DELETE /mailchimp/3.0/lists/{list_id}

List Members (Subscribers)

Members are contacts within an audience. The API uses MD5 hash of the lowercase email address as the subscriber identifier.

Get List Members

bash

GET /mailchimp/3.0/lists/{list_id}/members

Query parameters:

•status - Filter by subscription status (subscribed, unsubscribed, cleaned, pending, transactional)
•count - Number of records to return
•offset - Number of records to skip

Example:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists/abc123def4/members?status=subscribed&count=50')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json

{
  "members": [
    {
      "id": "f4b7c8d9e0",
      "email_address": "john@example.com",
      "status": "subscribed",
      "merge_fields": {
        "FNAME": "John",
        "LNAME": "Doe"
      },
      "tags": [
        {"id": 1, "name": "VIP"}
      ]
    }
  ],
  "total_items": 500
}

Get a Member

bash

GET /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}

The subscriber_hash is the MD5 hash of the lowercase email address.

Example:

bash

# For email "john@example.com", subscriber_hash = md5("john@example.com")
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists/abc123def4/members/b4c9a0d1e2f3g4h5')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Add a Member

bash

POST /mailchimp/3.0/lists/{list_id}/members
Content-Type: application/json

{
  "email_address": "newuser@example.com",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "Jane",
    "LNAME": "Smith"
  },
  "tags": ["Newsletter", "Premium"]
}

Example:

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'email_address': 'newuser@example.com', 'status': 'subscribed', 'merge_fields': {'FNAME': 'Jane', 'LNAME': 'Smith'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists/abc123def4/members', 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

Update a Member

bash

PATCH /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}

Example:

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'merge_fields': {'FNAME': 'Jane', 'LNAME': 'Doe'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists/abc123def4/members/b4c9a0d1e2f3g4h5', data=data, method='PATCH')
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

Add or Update a Member (Upsert)

bash

PUT /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}
Content-Type: application/json

{
  "email_address": "user@example.com",
  "status_if_new": "subscribed",
  "merge_fields": {
    "FNAME": "Jane",
    "LNAME": "Smith"
  }
}

Creates a new member or updates an existing one based on the email hash. Use status_if_new to set the status when creating a new member.

Delete a Member

Archives a member (can be re-added later):

bash

DELETE /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}

Returns 204 No Content on success.

To permanently delete (GDPR compliant):

bash

POST /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent

Member Tags

Get Member Tags

bash

GET /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}/tags

Add or Remove Tags

bash

POST /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}/tags
Content-Type: application/json

{
  "tags": [
    {"name": "VIP", "status": "active"},
    {"name": "Old Tag", "status": "inactive"}
  ]
}

Returns 204 No Content on success.

Segments

Get Segments

bash

GET /mailchimp/3.0/lists/{list_id}/segments

Example:

bash

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

Create a Segment

bash

POST /mailchimp/3.0/lists/{list_id}/segments
Content-Type: application/json

{
  "name": "Active Subscribers",
  "options": {
    "match": "all",
    "conditions": [
      {
        "condition_type": "EmailActivity",
        "field": "opened",
        "op": "date_within",
        "value": "30"
      }
    ]
  }
}

Update a Segment

bash

PATCH /mailchimp/3.0/lists/{list_id}/segments/{segment_id}

Get Segment Members

bash

GET /mailchimp/3.0/lists/{list_id}/segments/{segment_id}/members

Delete a Segment

bash

DELETE /mailchimp/3.0/lists/{list_id}/segments/{segment_id}

Returns 204 No Content on success.

Campaigns

Get All Campaigns

bash

GET /mailchimp/3.0/campaigns

Query parameters:

•type - Campaign type (regular, plaintext, absplit, rss, variate)
•status - Campaign status (save, paused, schedule, sending, sent)
•list_id - Filter by list ID
•count - Number of records to return
•offset - Number of records to skip

Example:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/campaigns?status=sent&count=20')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

json

{
  "campaigns": [
    {
      "id": "campaign123",
      "type": "regular",
      "status": "sent",
      "settings": {
        "subject_line": "Monthly Newsletter",
        "from_name": "Acme Corp"
      },
      "send_time": "2025-02-01T10:00:00Z",
      "report_summary": {
        "opens": 1500,
        "clicks": 300,
        "open_rate": 0.30,
        "click_rate": 0.06
      }
    }
  ],
  "total_items": 50
}

Get a Campaign

bash

GET /mailchimp/3.0/campaigns/{campaign_id}

Create a Campaign

bash

POST /mailchimp/3.0/campaigns
Content-Type: application/json

{
  "type": "regular",
  "recipients": {
    "list_id": "abc123def4"
  },
  "settings": {
    "subject_line": "Your Monthly Update",
    "from_name": "Acme Corp",
    "reply_to": "hello@acme.com"
  }
}

Example:

bash

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'type': 'regular', 'recipients': {'list_id': 'abc123def4'}, 'settings': {'subject_line': 'February Newsletter', 'from_name': 'Acme Corp', 'reply_to': 'newsletter@acme.com'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/campaigns', 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

Update a Campaign

bash

PATCH /mailchimp/3.0/campaigns/{campaign_id}

Delete a Campaign

bash

DELETE /mailchimp/3.0/campaigns/{campaign_id}

Returns 204 No Content on success.

Get Campaign Content

bash

GET /mailchimp/3.0/campaigns/{campaign_id}/content

Set Campaign Content

bash

PUT /mailchimp/3.0/campaigns/{campaign_id}/content
Content-Type: application/json

{
  "html": "<html><body><h1>Hello!</h1><p>Newsletter content here.</p></body></html>",
  "plain_text": "Hello! Newsletter content here."
}

Or use a template:

bash

PUT /mailchimp/3.0/campaigns/{campaign_id}/content
Content-Type: application/json

{
  "template": {
    "id": 12345,
    "sections": {
      "body": "<p>Custom content for the template section</p>"
    }
  }
}

Get Campaign Send Checklist

Check if a campaign is ready to send:

bash

GET /mailchimp/3.0/campaigns/{campaign_id}/send-checklist

Send a Campaign

bash

POST /mailchimp/3.0/campaigns/{campaign_id}/actions/send

Schedule a Campaign

bash

POST /mailchimp/3.0/campaigns/{campaign_id}/actions/schedule
Content-Type: application/json

{
  "schedule_time": "2025-03-01T10:00:00+00:00"
}

Cancel a Scheduled Campaign

bash

POST /mailchimp/3.0/campaigns/{campaign_id}/actions/cancel-send

Templates

Get All Templates

bash

GET /mailchimp/3.0/templates

Query parameters:

•type - Template type (user, base, gallery)
•count - Number of records to return
•offset - Number of records to skip

Example:

bash

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

Get a Template

bash

GET /mailchimp/3.0/templates/{template_id}

Get Template Default Content

bash

GET /mailchimp/3.0/templates/{template_id}/default-content

Create a Template

bash

POST /mailchimp/3.0/templates
Content-Type: application/json

{
  "name": "Newsletter Template",
  "html": "<html><body mc:edit=\"body\"><h1>Title</h1><p>Content here</p></body></html>"
}

Update a Template

bash

PATCH /mailchimp/3.0/templates/{template_id}

Delete a Template

bash

DELETE /mailchimp/3.0/templates/{template_id}

Returns 204 No Content on success.

Automations

Mailchimp's classic automations let you build email series triggered by dates, activities, or events.

Get All Automations

bash

GET /mailchimp/3.0/automations

Example:

bash

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

Get an Automation

bash

GET /mailchimp/3.0/automations/{workflow_id}

Start an Automation

bash

POST /mailchimp/3.0/automations/{workflow_id}/actions/start-all-emails

Pause an Automation

bash

POST /mailchimp/3.0/automations/{workflow_id}/actions/pause-all-emails

Get Automation Emails

bash

GET /mailchimp/3.0/automations/{workflow_id}/emails

Add Subscriber to Automation Queue

Manually add a subscriber to an automation workflow:

bash

POST /mailchimp/3.0/automations/{workflow_id}/emails/{workflow_email_id}/queue
Content-Type: application/json

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

Reports

Get Campaign Reports

bash

GET /mailchimp/3.0/reports

Query parameters:

•count - Number of records to return
•offset - Number of records to skip
•type - Campaign type

Example:

bash

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

Response:

json

{
  "reports": [
    {
      "id": "campaign123",
      "campaign_title": "Monthly Newsletter",
      "emails_sent": 5000,
      "opens": {
        "opens_total": 1500,
        "unique_opens": 1200,
        "open_rate": 0.24
      },
      "clicks": {
        "clicks_total": 450,
        "unique_clicks": 300,
        "click_rate": 0.06
      },
      "unsubscribed": 10,
      "bounce_rate": 0.02
    }
  ]
}

Get Campaign Report

bash

GET /mailchimp/3.0/reports/{campaign_id}

Get Campaign Open Details

bash

GET /mailchimp/3.0/reports/{campaign_id}/open-details

Get Campaign Click Details

bash

GET /mailchimp/3.0/reports/{campaign_id}/click-details

Get List Activity

bash

GET /mailchimp/3.0/lists/{list_id}/activity

Returns recent daily aggregated activity stats (unsubscribes, signups, opens, clicks) for up to 180 days.

Batch Operations

Process multiple operations in a single call.

Create Batch Operation

bash

POST /mailchimp/3.0/batches
Content-Type: application/json

{
  "operations": [
    {
      "method": "POST",
      "path": "/lists/abc123def4/members",
      "body": "{\"email_address\":\"user1@example.com\",\"status\":\"subscribed\"}"
    },
    {
      "method": "POST",
      "path": "/lists/abc123def4/members",
      "body": "{\"email_address\":\"user2@example.com\",\"status\":\"subscribed\"}"
    }
  ]
}

Get Batch Status

bash

GET /mailchimp/3.0/batches/{batch_id}

List All Batches

bash

GET /mailchimp/3.0/batches

Delete a Batch

bash

DELETE /mailchimp/3.0/batches/{batch_id}

Returns 204 No Content on success.

Pagination

Mailchimp uses offset-based pagination:

bash

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/lists?count=50&offset=100')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response includes total_items for calculating total pages:

json

{
  "lists": [...],
  "total_items": 250
}

Code Examples

JavaScript

javascript

const response = await fetch(
  'https://gateway.maton.ai/mailchimp/3.0/lists',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();

Python

python

import os
import requests
import hashlib

# Get lists
response = requests.get(
    'https://gateway.maton.ai/mailchimp/3.0/lists',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
data = response.json()

# Add a subscriber
list_id = 'abc123def4'
email = 'newuser@example.com'

response = requests.post(
    f'https://gateway.maton.ai/mailchimp/3.0/lists/{list_id}/members',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'email_address': email,
        'status': 'subscribed'
    }
)

# Get subscriber hash for updates
subscriber_hash = hashlib.md5(email.lower().encode()).hexdigest()

Notes

•List IDs are 10-character alphanumeric strings
•Subscriber hashes are MD5 hashes of lowercase email addresses
•Timestamps are in ISO 8601 format
•The API has a 120-second timeout on calls
•Maximum 1000 records per request for list endpoints
•"Audience" and "list" are used interchangeably (app vs API terminology)
•"Contact" and "member" are used interchangeably (app vs API terminology)
•IMPORTANT: When using curl commands, use curl -g when URLs contain brackets (fields[], sort[], records[]) 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. You may get "Invalid API key" errors when piping.

Response Codes

Status	Meaning
200	Success with response body
204	Success with no content (DELETE, some POST operations)
400	Bad request or missing Mailchimp connection
401	Invalid or missing Maton API key
403	Forbidden - insufficient permissions
404	Resource not found
405	Method not allowed
429	Rate limited
4xx/5xx	Passthrough error from Mailchimp API

Mailchimp error responses include detailed information:

json

{
  "type": "https://mailchimp.com/developer/marketing/docs/errors/",
  "title": "Invalid Resource",
  "status": 400,
  "detail": "The resource submitted could not be validated.",
  "instance": "abc123-def456",
  "errors": [
    {
      "field": "email_address",
      "message": "This value should be a valid email."
    }
  ]
}

Troubleshooting: Invalid API Key

When you receive a "Invalid API key" error, ALWAYS follow these steps before concluding there is an issue:

•Check that the MATON_API_KEY environment variable is set:

bash

echo $MATON_API_KEY

•Verify the API key is valid by listing connections:

bash

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

Mailchimp

Quick Start

Base URL

Authentication

Getting Your API Key

Connection Management

List Connections

Create Connection

Get Connection

Delete Connection

Specifying Connection

API Reference

Lists (Audiences)

Get All Lists

Get a List

Create a List

Update a List

Delete a List

List Members (Subscribers)

Get List Members

Get a Member

Add a Member

Update a Member

Add or Update a Member (Upsert)

Delete a Member

Member Tags

Get Member Tags

Add or Remove Tags

Segments

Get Segments

Create a Segment

Update a Segment

Get Segment Members

Delete a Segment

Campaigns

Get All Campaigns

Get a Campaign

Create a Campaign

Update a Campaign

Delete a Campaign

Get Campaign Content

Set Campaign Content

Get Campaign Send Checklist

Send a Campaign

Schedule a Campaign

Cancel a Scheduled Campaign

Templates

Get All Templates

Get a Template

Get Template Default Content

Create a Template

Update a Template

Delete a Template

Automations

Get All Automations

Get an Automation

Start an Automation

Pause an Automation

Get Automation Emails

Add Subscriber to Automation Queue

Reports

Get Campaign Reports

Get Campaign Report

Get Campaign Open Details

Get Campaign Click Details

Get List Activity

Batch Operations

Create Batch Operation

Get Batch Status

List All Batches

Delete a Batch

Pagination

Code Examples

JavaScript

Python

Notes

Response Codes

Troubleshooting: Invalid API Key

Resources