mailchimp

What this skill does

# 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

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

```bash
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

```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": "[email protected]",
    "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": "[email protected]",
      "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 "[email protected]", subscriber_hash = md5("[email protected]")
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": "[email protected]",
  "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': '[email protected]', 'status': 'subscribed', 'merge_fields': {'FNAME': 'Jane', 'LNAME': 'Smith'}}).encode()
req = urllib.request.Request('https://gateway.maton.ai/ma