Mailchimp Skill: Manage Email Campaigns and Subscriber Lists Without OAuth Complexity

14,272 downloads. The Mailchimp skill — by byungkyu via Maton — brings the full Mailchimp Marketing API into your AI agent workflow using the same managed OAuth gateway pattern that powers dozens of other byungkyu integrations on ClawHub.

If you've used the calendly-api, clickup-api, or google-meet skills, the authentication model is identical. Set MATON_API_KEY, connect your Mailchimp account once at ctrl.maton.ai, and every subsequent API call just works — no OAuth flow, no token refresh, no credential storage in your project.

The Problem It Solves

Integrating with Mailchimp directly requires implementing OAuth 2.0: redirect URLs, authorization codes, token exchange, refresh token management, and handling the case where a token expires mid-campaign. For an agent that needs to list audiences or check campaign stats, this infrastructure is entirely overhead.

Maton absorbs all of it. Your agent sends requests to gateway.maton.ai/mailchimp/... with your MATON_API_KEY, and Maton injects the correct OAuth token before proxying to api.mailchimp.com. The agent never holds Mailchimp credentials.

Core Concept: The Maton Gateway Pattern

All requests route through:

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

This path maps directly to the Mailchimp Marketing API. Every endpoint available at api.mailchimp.com/3.0/... is accessible at gateway.maton.ai/mailchimp/3.0/....

Authentication is a single header:

Authorization: Bearer $MATON_API_KEY

Deep Dive

List Audiences

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

Returns all audiences with subscriber counts, stats, and settings.

Campaign Operations

# List campaigns
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/campaigns?count=10&status=sent')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
# Create a campaign
data = json.dumps({
    "type": "regular",
    "recipients": {"list_id": "your_list_id"},
    "settings": {
        "subject_line": "Weekly Update",
        "from_name": "Your Name",
        "reply_to": "[email protected]"
    }
}).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')

Subscriber Management

# Add a member to a list
list_id = "your_list_id"
data = json.dumps({
    "email_address": "[email protected]",
    "status": "subscribed",
    "merge_fields": {"FNAME": "First", "LNAME": "Last"}
}).encode()
req = urllib.request.Request(
    f'https://gateway.maton.ai/mailchimp/3.0/lists/{list_id}/members',
    data=data, method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
 
# Update a member's status (e.g., unsubscribe)
import hashlib
email_hash = hashlib.md5("[email protected]".lower().encode()).hexdigest()
data = json.dumps({"status": "unsubscribed"}).encode()
req = urllib.request.Request(
    f'https://gateway.maton.ai/mailchimp/3.0/lists/{list_id}/members/{email_hash}',
    data=data, method='PATCH'
)

Campaign Reports

# Get stats for a campaign
campaign_id = "your_campaign_id"
req = urllib.request.Request(f'https://gateway.maton.ai/mailchimp/3.0/reports/{campaign_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')

Returns opens, clicks, bounce rate, unsubscribes, and geographic data.

Automations

# List automation workflows
req = urllib.request.Request('https://gateway.maton.ai/mailchimp/3.0/automations')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
# Trigger an automation for a specific subscriber
automation_id = "your_workflow_id"
data = json.dumps({"email_address": "[email protected]"}).encode()
req = urllib.request.Request(
    f'https://gateway.maton.ai/mailchimp/3.0/automations/{automation_id}/actions/start-all-emails',
    data=data, method='POST'
)

Multiple Mailchimp Accounts

For agencies managing multiple clients, specify which connection to use:

req.add_header('Maton-Connection', 'connection-id-here')

Manage connections at ctrl.maton.ai — create, list, and delete Mailchimp OAuth connections without touching your code.

What the Mailchimp API Covers

Comparison: Mailchimp Integration Options

How to Install

clawhub install mailchimp

Setup:

1. Get your Maton API key at maton.ai/settings
2. Set export MATON_API_KEY="your-key"
3. Create a Mailchimp connection at ctrl.maton.ai
4. Complete the OAuth flow in your browser

All API calls work immediately after the OAuth connection is established.

Practical Tips

1. Audience IDs are your primary key. Most operations require a list_id. List your audiences first and store the IDs — they don't change.
2. Member emails must be MD5-hashed for single-member operations. The Mailchimp API identifies members by a lowercase MD5 hash of their email address. Use hashlib.md5(email.lower().encode()).hexdigest() to generate it.
3. Use batch operations for bulk subscriber updates. The /lists/{list_id}/members batch endpoint handles up to 500 members per request — far more efficient than individual calls.
4. Campaign reports have a delay. Stats populate gradually after a send. For accurate open/click rates, wait at least 24 hours after the campaign send before pulling reports.
5. Automations require the workflow to be active. Triggering a subscriber into an automation workflow only works if the workflow is currently running (not paused or deleted).
6. Test with transactional emails first. If you're adding automation logic to an existing Mailchimp account, test on a non-production audience first to avoid accidentally triggering campaigns to real subscribers.

Considerations

• Maton API key is required. This skill requires a Maton account and API key. Maton's pricing covers the OAuth gateway service — check maton.ai for current plans.
• Mailchimp account required. You need a Mailchimp account (free tier works for basic operations) and must complete the OAuth connection at ctrl.maton.ai.
• Rate limits. Mailchimp's API rate limits apply at the account level. The Maton gateway passes these limits through — excessive calls from your agent will receive 429 responses.
• Data residency. Requests pass through Maton's gateway before reaching Mailchimp. If your organization has strict data residency requirements, review Maton's infrastructure location.
• Mailchimp's API versioning. All calls use the v3 API (/3.0/...), which is Mailchimp's current stable version.

The Bigger Picture

Email marketing is one of the highest-ROI marketing channels — and one of the most time-consuming to operate manually. The Mailchimp skill turns your AI agent into an email marketing analyst and operator: it can pull campaign performance across your entire history, segment audiences based on behavior, trigger automation workflows based on external events, and generate subscriber management reports on demand.

For agencies running multiple clients, the multi-connection model (via Maton-Connection header) means one agent installation can manage dozens of separate Mailchimp accounts — something that would otherwise require building and maintaining a multi-tenant OAuth system.

View the skill on ClawHub: mailchimp