通过托管 OAuth 认证访问 Mailchimp Marketing API。管理邮件营销的受众、活动、模板、自动化、报告和订阅者。

快速开始

# 列出所有受众
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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

• 在 maton.ai 登录或创建账户
• 访问 maton.ai/settings
• 复制您的 API 密钥

连接管理

在 https://ctrl.maton.ai 管理您的 Mailchimp OAuth 连接。

列出连接

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

添加连接

在浏览器中访问 https://ctrl.maton.ai/connections/mailchimp/new 以连接您的 Mailchimp 账户。

API 端点

受众（列表）

# 列出所有受众
GET /mailchimp/3.0/lists
# 获取特定受众
GET /mailchimp/3.0/lists/{listId}
# 创建受众
POST /mailchimp/3.0/lists
# 更新受众
PATCH /mailchimp/3.0/lists/{listId}
# 删除受众
DELETE /mailchimp/3.0/lists/{listId}

订阅者

# 列出受众成员
GET /mailchimp/3.0/lists/{listId}/members
# 添加/更新订阅者
PUT /mailchimp/3.0/lists/{listId}/members/{subscriberHash}
# 获取特定订阅者
GET /mailchimp/3.0/lists/{listId}/members/{subscriberHash}
# 取消订阅
PATCH /mailchimp/3.0/lists/{listId}/members/{subscriberHash}
# 永久删除
DELETE /mailchimp/3.0/lists/{listId}/members/{subscriberHash}

活动

# 列出活动
GET /mailchimp/3.0/campaigns
# 创建活动
POST /mailchimp/3.0/campaigns
# 获取特定活动
GET /mailchimp/3.0/campaigns/{campaignId}
# 更新活动
PATCH /mailchimp/3.0/campaigns/{campaignId}
# 发送活动
POST /mailchimp/3.0/campaigns/{campaignId}/actions/send
# 删除活动
DELETE /mailchimp/3.0/campaigns/{campaignId}

模板

# 列出模板
GET /mailchimp/3.0/templates
# 创建模板
POST /mailchimp/3.0/templates
# 获取特定模板
GET /mailchimp/3.0/templates/{templateId}
# 更新模板
PATCH /mailchimp/3.0/templates/{templateId}
# 删除模板
DELETE /mailchimp/3.0/templates/{templateId}

自动化

# 列出自动化
GET /mailchimp/3.0/automations
# 创建自动化
POST /mailchimp/3.0/automations
# 获取特定自动化
GET /mailchimp/3.0/automations/{workflowId}
# 启动自动化
POST /mailchimp/3.0/automations/{workflowId}/actions/start-all-emails
# 暂停自动化
POST /mailchimp/3.0/automations/{workflowId}/actions/pause-all-emails

报告

# 获取活动报告
GET /mailchimp/3.0/reports/{campaignId}
# 获取打开详情
GET /mailchimp/3.0/reports/{campaignId}/open-details
# 获取点击详情
GET /mailchimp/3.0/reports/{campaignId}/click-details
# 获取订阅者活动
GET /mailchimp/3.0/reports/{campaignId}/sub-activity

使用示例

添加订阅者

python <<'EOF'
import urllib.request, os, json
list_id = "your-list-id"
subscriber_data = {
  "email_address": "subscriber@example.com",
  "status": "subscribed",
  "merge_fields": {
    "FNAME": "John",
    "LNAME": "Doe"
  }
}
# 计算订阅者哈希（MD5 of lowercase email）
import hashlib
email_lower = subscriber_data["email_address"].lower()
subscriber_hash = hashlib.md5(email_lower.encode()).hexdigest()
req = urllib.request.Request(
  f'https://gateway.maton.ai/mailchimp/3.0/lists/{list_id}/members/{subscriber_hash}',
  data=json.dumps(subscriber_data).encode('utf-8'),
  headers={
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'Content-Type': 'application/json'
  },
  method='PUT'
)
result = json.load(urllib.request.urlopen(req))
print(json.dumps(result, indent=2))
EOF

创建并发送活动

python <<'EOF'
import urllib.request, os, json
# 第一步：创建活动
campaign_data = {
  "recipients": {
    "list_id": "your-list-id"
  },
  "type": "regular",
  "settings": {
    "subject_line": "我们的新产品推出了！",
    "preview_text": "查看我们最新的产品更新",
    "title": "2026 年 6 月产品更新",
    "from_name": "您的公司",
    "reply_to": "hello@yourcompany.com"
  }
}
req = urllib.request.Request(
  'https://gateway.maton.ai/mailchimp/3.0/campaigns',
  data=json.dumps(campaign_data).encode('utf-8'),
  headers={
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'Content-Type': 'application/json'
  }
)
campaign = json.load(urllib.request.urlopen(req))
campaign_id = campaign['id']
print(f"已创建活动 ID: {campaign_id}")
# 第二步：添加内容
content_data = {
  "html": "
大家好！
查看我们的最新产品...
"
}
req = urllib.request.Request(
  f'https://gateway.maton.ai/mailchimp/3.0/campaigns/{campaign_id}/content',
  data=json.dumps(content_data).encode('utf-8'),
  headers={
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'Content-Type': 'application/json'
  },
  method='PUT'
)
json.load(urllib.request.urlopen(req))
print("已添加活动内容")
# 第三步：发送活动
req = urllib.request.Request(
  f'https://gateway.maton.ai/mailchimp/3.0/campaigns/{campaign_id}/actions/send',
  data=b'',
  headers={
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'
  }
)
urllib.request.urlopen(req)
print("活动已发送！")
EOF

获取活动报告

python <<'EOF'
import urllib.request, os, json
campaign_id = "your-campaign-id"
req = urllib.request.Request(
  f'https://gateway.maton.ai/mailchimp/3.0/reports/{campaign_id}',
  headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
report = json.load(urllib.request.urlopen(req))
print(f"打开数: {report['opens']['opens_total']}")
print(f"点击率: {report['clicks']['clicks_total']}")
print(f"退订数: {report['unsubscribes']['unsubscribes_total']}")
EOF

订阅者状态

• subscribed - 订阅者已选择加入
• unsubscribed - 订阅者已取消订阅
• cleaned - 订阅者已被清理（硬退信）
• pending - 订阅者需要确认（双重选择加入）
• transactional - 仅用于事务性邮件

合并字段

常见的合并字段：

• FNAME - 名字
• LNAME - 姓氏
• ADDRESS - 地址
• PHONE - 电话号码
• BIRTHDAY - 生日

兴趣类别

使用兴趣类别来细分您的受众：

# 获取兴趣类别
GET /mailchimp/3.0/lists/{listId}/interest-categories
# 获取特定类别的兴趣
GET /mailchimp/3.0/lists/{listId}/interest-categories/{categoryId}/interests

标签

使用标签来组织订阅者：

# 列出订阅者的标签
GET /mailchimp/3.0/lists/{listId}/members/{subscriberHash}/tags
# 添加标签
POST /mailchimp/3.0/lists/{listId}/members/{subscriberHash}/tags

错误处理

所有错误响应都将包含状态码和错误消息：

{
  "type": "http://developer.mailchimp.com/documentation/mailchimp/guides/error-glossary/",
  "title": "Error Title",
  "status": 400,
  "detail": "Error description",
  "instance": "request-id"
}

常见的状态码：

• 400 - 错误请求
• 401 - 未授权
• 403 - 禁止访问
• 404 - 未找到
• 405 - 方法不允许
• 422 - 无法处理的实体
• 429 - 请求过多（速率限制）
• 500 - 服务器内部错误

限制

• 速率限制：每个数据中心每 15 分钟最多 10 次并发连接和 1000 次请求
• 订阅者导入：每次最多 500 个订阅者
• 活动大小：HTML 最多 1024KB

合规性

• 确保遵守当地电子邮件法律（CAN-SPAM、GDPR 等）
• 始终提供退订链接
• 保留订阅者选择加入的记录
• 尊重退订请求（法律要求在 10 个工作日内处理）

支持

如遇到问题，请访问：

• Maton 文档
• Mailchimp API 文档
• Mailchimp 开发者论坛