介绍
# Mailchimp
通过托管的 OAuth 身份验证访问 Mailchimp Marketing API。管理电子邮件营销的受众（Audiences）、活动（Campaigns）、模板、自动化、报告和订阅者。
## 快速开始
```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 ```
## 基础 URL
``` https://gateway.maton.ai/mailchimp/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Mailchimp API 端点路径（例如 `3.0/lists`）。网关会将请求代理到您的 Mailchimp 数据中心，并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中提供 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Mailchimp OAuth 连接。
### 列出连接
```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 ```
### 创建连接
```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 ```
### 获取连接
```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 ```
**响应：** ```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": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```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 ```
### 指定连接
如果您有多个 Mailchimp 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```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 ```
如果省略，网关将使用默认（最旧）的活动连接。
## API 参考
### 列表（受众）
在 Mailchimp 应用中，“audience”（受众）是常用术语，但 API 在端点中使用“lists”（列表）。
#### 获取所有列表
```bash GET /mailchimp/3.0/lists ```
查询参数： - `count` - 要返回的记录数（默认 10，最大 1000） - `offset` - 要跳过的记录数（用于分页） - `fields` - 要包含的字段逗号分隔列表 - `exclude_fields` - 要排除的字段逗号分隔列表
**示例：**
```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 ```
**响应：** ```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 } ```
#### 获取特定列表
```bash GET /mailchimp/3.0/lists/{list_id} ```
**示例：**
```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 ```
#### 创建列表
```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 } ```
#### 更新列表
```bash PATCH /mailchimp/3.0/lists/{list_id} ```
#### 删除列表
```bash DELETE /mailchimp/3.0/lists/{list_id} ```
### 列表成员（订阅者）
成员是受众中的联系人。API 使用小写电子邮件地址的 MD5 哈希值作为订阅者标识符。
#### 获取列表成员
```bash GET /mailchimp/3.0/lists/{list_id}/members ```
查询参数： - `status` - 按订阅状态筛选（subscribed, unsubscribed, cleaned, pending, transactional） - `count` - 要返回的记录数 - `offset` - 要跳过的记录数
**示例：**
```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 ```
**响应：** ```json { "members": [ { "id": "f4b7c8d9e0", "email_address": "[email protected]", "status": "subscribed", "merge_fields": { "FNAME": "John", "LNAME": "Doe" }, "tags": [ {"id": 1, "name": "VIP"} ] } ], "total_items": 500 } ```
#### 获取特定成员
```bash GET /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash} ```
`subscriber_hash` 是小写电子邮件地址的 MD5 哈希值。
**示例：**
```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 ```
#### 添加成员
```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"] } ```
**示例：**
```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/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 ```
#### 更新成员
```bash PATCH /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash} ```
**示例：**
```bash 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 ```
#### 添加或更新成员（Upsert）
```bash PUT /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash} Content-Type: application/json
{ "email_address": "[email protected]", "status_if_new": "subscribed", "merge_fields": { "FNAME": "Jane", "LNAME": "Smith" } } ```
创建新成员或根据电子邮件哈希更新现有成员。使用 `status_if_new` 在创建新成员时设置状态。
#### 删除成员
存档成员（可以稍后重新添加）：
```bash DELETE /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash} ```
成功时返回 `204 No Content`。
要永久删除（符合 GDPR）：
```bash POST /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent ```
### 成员标签
#### 获取成员标签
```bash GET /mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}/tags ```
#### 添加或移除标签
```bash 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"} ] } ```
成功时返回 `204 No Content`。
### 分段
#### 获取分段
```bash GET /mailchimp/3.0/lists/{list_id}/segments ```
**示例：**
```bash 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 ```
#### 创建分段
```bash 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" } ] } } ```
#### 更新分段
```bash PATCH /mailchimp/3.0/lists/{list_id}/segments/{segment_id} ```
#### 获取分段成员
```bash GET /mailchimp/3.0/lists/{list_id}/segments/{segment_id}/members ```
#### 删除分段
```bash DELETE /mailchimp/3.0/lists/{list_id}/segments/{segment_id} ```
成功时返回 `204 No Content`。
### 活动
#### 获取所有活动
```bash GET /mailchimp/3.0/campaigns ```
查询参数： - `type` - 活动类型（regular, plaintext, absplit, rss, variate） - `status` - 活动状态（save, paused, schedule, sending, sent） - `list_id` - 按列表 ID 筛选 - `count` - 要返回的记录数 - `offset` - 要跳过的记录数
**示例：**
```bash 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 ```
**响应：** ```json { "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 } ```
#### 获取特定活动
```bash GET /mailchimp/3.0/campaigns/{campaign_id} ```
#### 创建活动
```bash 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": "[email protected]" } } ```
**示例：**
```bash 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': '[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') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 更新活动
```bash PATCH /mailchimp/3.0/campaigns/{campaign_id} ```
#### 删除活动
```bash DELETE /mailchimp/3.0/campaigns/{campaign_id} ```
成功时返回 `204 No Content`。
#### 获取活动内容
```bash GET /mailchimp/3.0/campaigns/{campaign_id}/content ```
#### 设置活动内容
```bash 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." } ```
或使用模板：
```bash 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>" } } } ```
#### 获取活动发送检查清单
检查活动是否准备好发送：
```bash GET /mailchimp/3.0/campaigns/{campaign_id}/send-checklist ```
#### 发送活动
```bash POST /mailchimp/3.0/campaigns/{campaign_id}/actions/send ```
#### 安排活动
```bash POST /mailchimp/3.0/campaigns/{campaign_id}/actions/schedule Content-Type: application/json
{ "schedule_time": "2025-03-01T10:00:00+00:00" } ```
#### 取消计划的活动
```bash POST /mailchimp/3.0/campaigns/{campaign_id}/actions/cancel-send ```
### 模板
#### 获取所有模板
```bash GET /mailchimp/3.0/templates ```
查询参数： - `type` - 模板类型（user, base, gallery） - `count` - 要返回的记录数 - `offset` - 要跳过的记录数
**示例：**
```bash 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 ```
#### 获取特定模板
```bash GET /mailchimp/3.0/templates/{template_id} ```
#### 获取模板默认内容
```bash GET /mailchimp/3.0/templates/{template_id}/default-content ```
#### 创建模板
```bash 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>" } ```
#### 更新模板
```bash PATCH /mailchimp/3.0/templates/{template_id} ```
#### 删除模板
```bash DELETE /mailchimp/3.0/templates/{template_id} ```
成功时返回 `204 No Content`。
### 自动化
Mailchimp 的经典自动化允许您构建由日期、活动或事件触发的电子邮件系列。
#### 获取所有自动化
```bash GET /mailchimp/3.0/automations ```
**示例：**
```bash 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 ```
#### 获取特定自动化
```bash GET /mailchimp/3.0/automations/{workflow_id} ```
#### 启动自动化
```bash POST /mailchimp/3.0/automations/{workflow_id}/actions/start-all-emails ```
#### 暂停自动化
```bash POST /mailchimp/3.0/automations/{workflow_id}/actions/pause-all-emails ```
#### 获取自动化邮件
```bash GET /mailchimp/3.0/automations/{workflow_id}/emails ```
#### 将订阅者添加到自动化队列
手动将订阅者添加到自动化工作流：
```bash POST /mailchimp/3.0/automations/{workflow_id}/emails/{workflow_email_id}/queue Content-Type: application/json
{ "email_address": "[email protected]" } ```
### 报告
#### 获取活动报告
```bash GET /mailchimp/3.0/reports ```
查询参数： - `count` - 要返回的记录数 - `offset` - 要跳过的记录数 - `type` - 活动类型
**示例：**
```bash 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 ```
**响应：** ```json { "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 } ] } ```
#### 获取特定活动报告
```bash GET /mailchimp/3.0/reports/{campaign_id} ```
#### 获取活动打开详情
```bash GET /mailchimp/3.0/reports/{campaign_id}/open-details ```
#### 获取活动点击详情
```bash GET /mailchimp/3.0/reports/{campaign_id}/click-details ```
#### 获取列表活动
```bash GET /mailchimp/3.0/lists/{list_id}/activity ```
返回最近 180 天的每日汇总活动统计信息（取消订阅、注册、打开、点击）。
### 批量操作
在单个调用中处理多个操作。
#### 创建批量操作
```bash POST /mailchimp/3.0/batches Content-Type: application/json
{ "operations": [ { "method": "POST", "path": "/lists/abc123def4/members", "body": "{\"email_address\":\"[email protected]\",\"status\":\"subscribed\"}" }, { "method": "POST", "path": "/lists/abc123def4/members", "body": "{\"email_address\":\"[email protected]\",\"status\":\"subscribed\"}" } ] } ```
#### 获取批量状态
```bash GET /mailchimp/3.0/batches/{batch_id} ```
#### 列出所有批次
```bash GET /mailchimp/3.0/batches ```
#### 删除批次
```bash DELETE /mailchimp/3.0/batches/{batch_id} ```
成功时返回 `204 No Content`。
## 分页
Mailchimp 使用基于偏移量的分页：
```bash 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)) EOF ```
响应包含 `total_items` 用于计算总页数：
```json { "lists": [...], "total_items": 250 } ```
## 代码示例
### JavaScript
```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
```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 = '[email protected]'
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() ```
## 注意事项
- 列表 ID 是 10 个字符的字母数字字符串 - 订阅者哈希是小写电子邮件地址的 MD5 哈希值 - 时间戳采用 ISO 8601 格式 - API 调用有 120 秒的超时限制 - 列表端点每个请求最多 1000 条记录 - “Audience”（受众）和“list”（列表）互换使用（应用术语与 API 术语） - “Contact”（联系人）和“member”（成员）互换使用（应用术语与 API 术语） - 重要：使用 curl 命令时，如果 URL 包含方括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传输到 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确扩展。通过管道传输时，您可能会收到“Invalid API key”错误。
## 响应代码
| 状态 | 含义 | |--------|---------| | 200 | 成功，带有响应体 | | 204 | 成功，无内容（DELETE，某些 POST 操作） | | 400 | 错误的请求或缺少 Mailchimp 连接 | | 401 | 无效或缺少 Maton API 密钥 | | 403 | 禁止访问 - 权限不足 | | 404 | 未找到资源 | | 405 | 不允许的方法 | | 429 | 请求频率受限 | | 4xx/5xx | 来自 Mailchimp API 的透传错误 |
Mailchimp 错误响应包含详细信息：
```json { "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." } ] } ```
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接验证 API 密钥是否有效：
```bash 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)) EOF ```
### 故障排除：应用名称无效
1. 确保您的 URL 路径以 `mailchimp` 开头。例如：
- 正确：`https://gateway.maton.ai/mailchimp/3.0/lists` - 错误：`https://gateway.maton.ai/3.0/lists`
## 资源
- [Mailchimp Marketing API 文档](https://mailchimp.com/developer/marketing/) - [API 参考](https://mailchimp.com/developer/marketing/api/) - [快速开始指南](https://mailchimp.com/developer/marketing/guides/quick-start/) - [发布说明](https://mailchimp.com/developer/release-notes/) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])