Mailchimp

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

Reference

Get All Lists

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

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

GET /mailchimp/3.0/lists/{list_id}

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

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

PATCH /mailchimp/3.0/lists/{list_id}

Delete a List

DELETE /mailchimp/3.0/lists/{list_id}

Get List Members

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

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

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

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

Example:

# For email "john@example.com", subscriber_hash = md5("john@example.com")
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

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:

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://api.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

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

Example:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'merge_fields': {'FNAME': 'Jane', 'LNAME': 'Doe'}}).encode()
req = urllib.request.Request('https://api.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)

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):

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

Returns 204 No Content on success.

To permanently delete (GDPR compliant):

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

Get Member Tags

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

Add or Remove Tags

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.

Get Segments

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

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

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

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

Get Segment Members

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

Delete a Segment

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

Returns 204 No Content on success.

Get All Campaigns

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

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

GET /mailchimp/3.0/campaigns/{campaign_id}

Create a Campaign

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:

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://api.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

PATCH /mailchimp/3.0/campaigns/{campaign_id}

Delete a Campaign

DELETE /mailchimp/3.0/campaigns/{campaign_id}

Returns 204 No Content on success.

Get Campaign Content

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

Set Campaign Content

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:

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:

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

Send a Campaign

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

Schedule a Campaign

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

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

Get All Templates

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:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

GET /mailchimp/3.0/templates/{template_id}

Get Template Default Content

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

Create a Template

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

PATCH /mailchimp/3.0/templates/{template_id}

Delete a Template

DELETE /mailchimp/3.0/templates/{template_id}

Returns 204 No Content on success.

Get All Automations

GET /mailchimp/3.0/automations

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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

GET /mailchimp/3.0/automations/{workflow_id}

Start an Automation

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

Pause an Automation

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

Get Automation Emails

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

Add Subscriber to Automation Queue

Manually add a subscriber to an automation workflow:

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

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

Get Campaign Reports

GET /mailchimp/3.0/reports

Query parameters:

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

Example:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://api.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:

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

GET /mailchimp/3.0/reports/{campaign_id}

Get Campaign Open Details

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

Get Campaign Click Details

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

Get List Activity

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

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

Create Batch Operation

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

GET /mailchimp/3.0/batches/{batch_id}

List All Batches

GET /mailchimp/3.0/batches

Delete a Batch

DELETE /mailchimp/3.0/batches/{batch_id}

Returns 204 No Content on success.

Mailchimp

On this page