🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Mailchimp
πŸ¦€ ClawHub

Mailchimp

by @byungkyu

Mailchimp Marketing API integration with managed OAuth. Access audiences, campaigns, templates, automations, reports, and manage subscribers. Use this skill...

Versionv1.0.4
Downloads16,467
Installs15
Stars⭐ 12
Comments3
#crypto-defi#security#email-marketing#legal#automation
TERMINAL
clawhub install mailchimp

πŸ“– About This Skill

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

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

Maton 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 2. Go to maton.ai/settings 3. Copy your API key

Connection Management

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

List Connections

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

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'mailchimp'}).encode()
req = urllib.request.Request('https://api.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://api.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": "{connection_id}",
    "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://api.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:

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

If you have multiple connections, always include this header to ensure requests go to the intended account.

Security & Permissions

  • Access is scoped to audiences, campaigns, templates, automations, reports, and manage subscribers within the connected Mailchimp account.
  • All write operations require explicit user approval. Before executing any create, update, or delete call, confirm the target resource and intended effect with the user.

    • 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/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}

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

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

    Campaigns

    #### 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": "
    Hello!
    Newsletter content here.
    ",
  "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": "
    Custom content for the template section
    "
    }
  }
}

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

    Templates

    #### 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": "
    Title
    Content here
    "
}

    #### 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://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"
}

    Reports

    #### 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.

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

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

    Code Examples

    JavaScript

    const response = await fetch(
  'https://api.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://api.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://api.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:

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

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

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

  • Correct: https://api.maton.ai/mailchimp/3.0/lists
  • Incorrect: https://api.maton.ai/3.0/lists

    • Resources

  • Mailchimp Marketing API Documentation
  • API Reference
  • Quick Start Guide
  • Release Notes
  • Maton Community
  • Maton Support

    • πŸ’‘ Examples

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

    πŸ“‹ Tips & Best Practices

  • 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.