Mailchimp
name: mailchimp
by byungkyu · published 2026-03-22
$ claw add gh:byungkyu/byungkyu-mailchimp---
name: mailchimp
description: |
Mailchimp Marketing API integration with managed OAuth. Access audiences, campaigns, templates, automations, reports, and manage subscribers. Use this skill when users want to manage email marketing, subscriber lists, or automate email campaigns. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway).
compatibility: Requires network access and valid Maton API key
metadata:
author: maton
version: "1.0"
clawdbot:
emoji: 🧠
requires:
env:
- MATON_API_KEY
---
# Mailchimp
Access the Mailchimp Marketing API with managed OAuth authentication. Manage audiences, campaigns, templates, automations, reports, and subscribers for email marketing.
Quick Start
# 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))
EOFBase URL
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:
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](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key
Connection Management
Manage your Mailchimp 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=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))
EOFCreate Connection
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))
EOFGet 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": "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
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))
EOFSpecifying Connection
If you have multiple Mailchimp 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/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))
EOFIf 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
GET /mailchimp/3.0/listsQuery parameters:
**Example:**
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:**
{
"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://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
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}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
GET /mailchimp/3.0/lists/{list_id}/membersQuery parameters:
**Example:**
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:**
{
"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://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
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://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
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://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)
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-permanentMember Tags
#### 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.
Segments
#### Get Segments
GET /mailchimp/3.0/lists/{list_id}/segments**Example:**
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
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.
Campaigns
#### Get All Campaigns
GET /mailchimp/3.0/campaignsQuery parameters:
**Example:**
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:**
{
"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://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
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-sendTemplates
#### Get All Templates
GET /mailchimp/3.0/templatesQuery parameters:
**Example:**
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
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.
Automations
Mailchimp's classic automations let you build email series triggered by dates, activities, or events.
#### Get All Automations
GET /mailchimp/3.0/automations**Example:**
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
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"
}Reports
#### Get Campaign Reports
GET /mailchimp/3.0/reportsQuery parameters:
**Example:**
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:**
{
"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}/activityReturns 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
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.
Pagination
Mailchimp uses offset-based pagination:
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))
EOFResponse includes `total_items` for calculating total pages:
{
"lists": [...],
"total_items": 250
}Code Examples
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
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
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:
{
"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: API Key Issues
1. Check that the `MATON_API_KEY` environment variable is set:
echo $MATON_API_KEY2. 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))
EOFTroubleshooting: Invalid App Name
1. Ensure your URL path starts with `mailchimp`. For example:
Resources
More tools from the same signal band
Order food/drinks (点餐) on an Android device paired as an OpenClaw node. Uses in-app menu and cart; add goods, view cart, submit order (demo, no real payment).
Sign plugins, rotate agent credentials without losing identity, and publicly attest to plugin behavior with verifiable claims and authenticated transfers.
The philosophical layer for AI agents. Maps behavior to Spinoza's 48 affects, calculates persistence scores, and generates geometric self-reports. Give your...