介绍
# MailerLite
通过托管的 OAuth 身份验证访问 MailerLite API。管理订阅者、群组、营销活动、自动化、表单、字段、细分和 Webhook。
## 快速开始
```bash # List subscribers python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/mailerlite/api/subscribers?limit=10') 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/mailerlite/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 MailerLite API 端点路径。网关将请求代理到 `connect.mailerlite.com` 并自动注入您的 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` 管理您的 MailerLite OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=mailerlite&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': 'mailerlite'}).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": "mailerlite", "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 ```
### 指定连接
如果您有多个 MailerLite 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/mailerlite/api/subscribers') 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 参考
### 订阅者操作
#### 列出订阅者
```bash GET /mailerlite/api/subscribers ```
查询参数： - `filter[status]` - 按状态筛选：`active`、`unsubscribed`、`unconfirmed`、`bounced`、`junk` - `limit` - 每页结果数（默认：25） - `cursor` - 分页游标 - `include` - 包含相关数据：`groups`
#### 获取订阅者
```bash GET /mailerlite/api/subscribers/{subscriber_id_or_email} ```
#### 创建/更新订阅者
```bash POST /mailerlite/api/subscribers Content-Type: application/json
{ "email": "[email protected]", "fields": { "name": "John Doe", "company": "Acme Inc" }, "groups": ["12345678901234567"], "status": "active" } ```
对于新订阅者返回 201，对于更新返回 200。
#### 更新订阅者
```bash PUT /mailerlite/api/subscribers/{subscriber_id} Content-Type: application/json
{ "fields": { "name": "Jane Doe" }, "status": "active" } ```
#### 删除订阅者
```bash DELETE /mailerlite/api/subscribers/{subscriber_id} ```
#### 获取订阅者活动
```bash GET /mailerlite/api/subscribers/{subscriber_id}/activity-log ```
查询参数： - `filter[log_name]` - 按活动类型筛选：`campaign_send`、`automation_email_sent`、`email_open`、`link_click`、`email_bounce`、`spam_complaint`、`unsubscribed` - `limit` - 每页结果数（默认：100） - `page` - 页码（从 1 开始）
#### 忘记订阅者 (GDPR)
```bash POST /mailerlite/api/subscribers/{subscriber_id}/forget ```
### 群组操作
#### 列出群组
```bash GET /mailerlite/api/groups ```
查询参数： - `limit` - 每页结果数 - `page` - 页码（从 1 开始） - `filter[name]` - 按名称筛选（部分匹配） - `sort` - 排序方式：`name`、`total`、`open_rate`、`click_rate`、`created_at`（前面加 `-` 表示降序）
#### 创建群组
```bash POST /mailerlite/api/groups Content-Type: application/json
{ "name": "Newsletter Subscribers" } ```
#### 更新群组
```bash PUT /mailerlite/api/groups/{group_id} Content-Type: application/json
{ "name": "Updated Group Name" } ```
#### 删除群组
```bash DELETE /mailerlite/api/groups/{group_id} ```
#### 获取群组订阅者
```bash GET /mailerlite/api/groups/{group_id}/subscribers ```
查询参数： - `filter[status]` - 按状态筛选：`active`、`unsubscribed`、`unconfirmed`、`bounced`、`junk` - `limit` - 每页结果数（1-1000，默认：50） - `cursor` - 分页游标
#### 将订阅者分配到群组
```bash POST /mailerlite/api/subscribers/{subscriber_id}/groups/{group_id} ```
#### 从群组中移除订阅者
```bash DELETE /mailerlite/api/subscribers/{subscriber_id}/groups/{group_id} ```
### 营销活动操作
#### 列出营销活动
```bash GET /mailerlite/api/campaigns ```
查询参数： - `filter[status]` - 按状态筛选：`sent`、`draft`、`ready` - `filter[type]` - 按类型筛选：`regular`、`ab`、`resend`、`rss` - `limit` - 每页结果数：10、25、50 或 100（默认：25） - `page` - 页码（从 1 开始）
#### 获取营销活动
```bash GET /mailerlite/api/campaigns/{campaign_id} ```
#### 创建营销活动
```bash POST /mailerlite/api/campaigns Content-Type: application/json
{ "name": "My Newsletter", "type": "regular", "emails": [ { "subject": "Weekly Update", "from_name": "Newsletter", "from": "[email protected]" } ], "groups": ["12345678901234567"] } ```
#### 更新营销活动
```bash PUT /mailerlite/api/campaigns/{campaign_id} Content-Type: application/json
{ "name": "Updated Campaign Name", "emails": [ { "subject": "New Subject Line", "from_name": "Newsletter", "from": "[email protected]" } ] } ```
注意：只有草稿状态的营销活动可以更新。
#### 计划营销活动
```bash POST /mailerlite/api/campaigns/{campaign_id}/schedule Content-Type: application/json
{ "delivery": "instant" } ```
对于计划发送： ```json { "delivery": "scheduled", "schedule": { "date": "2026-03-15", "hours": "10", "minutes": "30" } } ```
#### 取消营销活动
```bash POST /mailerlite/api/campaigns/{campaign_id}/cancel ```
将就绪状态的营销活动恢复为草稿状态。
#### 删除营销活动
```bash DELETE /mailerlite/api/campaigns/{campaign_id} ```
#### 获取营销活动订阅者活动
```bash GET /mailerlite/api/campaigns/{campaign_id}/reports/subscriber-activity ```
查询参数： - `filter[type]` - 按活动筛选：`opened`、`unopened`、`clicked`、`unsubscribed`、`forwarded`、`hardbounced`、`softbounced`、`junk` - `filter[search]` - 按电子邮件搜索 - `limit` - 每页结果数（10、25、50 或 100） - `page` - 页码（从 1 开始）
### 自动化操作
#### 列出自动化
```bash GET /mailerlite/api/automations ```
查询参数： - `filter[enabled]` - 按状态筛选：`true` 或 `false` - `filter[name]` - 按名称筛选 - `filter[group]` - 按群组 ID 筛选 - `page` - 页码（从 1 开始） - `limit` - 每页结果数（默认：10）
#### 获取自动化
```bash GET /mailerlite/api/automations/{automation_id} ```
#### 创建自动化
```bash POST /mailerlite/api/automations Content-Type: application/json
{ "name": "Welcome Series" } ```
创建一个草稿自动化。
#### 获取自动化活动
```bash GET /mailerlite/api/automations/{automation_id}/activity ```
查询参数： - `filter[status]` - 必填：`completed`、`active`、`canceled`、`failed` - `filter[date_from]` - 开始日期 (Y-m-d) - `filter[date_to]` - 结束日期 (Y-m-d) - `filter[search]` - 按电子邮件搜索 - `page` - 页码（从 1 开始） - `limit` - 每页结果数（默认：10）
#### 删除自动化
```bash DELETE /mailerlite/api/automations/{automation_id} ```
### 字段操作
#### 列出字段
```bash GET /mailerlite/api/fields ```
查询参数： - `limit` - 每页结果数（最多 100） - `page` - 页码（从 1 开始） - `filter[keyword]` - 按关键词筛选（部分匹配） - `filter[type]` - 按类型筛选：`text`、`number`、`date` - `sort` - 排序方式：`name`、`type`（前面加 `-` 表示降序）
#### 创建字段
```bash POST /mailerlite/api/fields Content-Type: application/json
{ "name": "Company", "type": "text" } ```
#### 更新字段
```bash PUT /mailerlite/api/fields/{field_id} Content-Type: application/json
{ "name": "Organization" } ```
#### 删除字段
```bash DELETE /mailerlite/api/fields/{field_id} ```
### 细分操作
#### 列出细分
```bash GET /mailerlite/api/segments ```
查询参数： - `limit` - 每页结果数（最多 250） - `page` - 页码（从 1 开始）
#### 获取细分订阅者
```bash GET /mailerlite/api/segments/{segment_id}/subscribers ```
查询参数： - `filter[status]` - 按状态筛选：`active`、`unsubscribed`、`unconfirmed`、`bounced`、`junk` - `limit` - 每页结果数 - `cursor` - 分页游标
#### 更新细分
```bash PUT /mailerlite/api/segments/{segment_id} Content-Type: application/json
{ "name": "High Engagement Subscribers" } ```
#### 删除细分
```bash DELETE /mailerlite/api/segments/{segment_id} ```
### 表单操作
#### 列出表单
```bash GET /mailerlite/api/forms/{type} ```
路径参数： - `type` - 表单类型：`popup`、`embedded`、`promotion`
查询参数： - `limit` - 每页结果数 - `page` - 页码（从 1 开始） - `filter[name]` - 按名称筛选（部分匹配） - `sort` - 排序方式：`created_at`、`name`、`conversions_count`、`opens_count`、`visitors`、`conversion_rate`、`last_registration_at`（前面加 `-` 表示降序）
#### 获取表单
```bash GET /mailerlite/api/forms/{form_id} ```
#### 更新表单
```bash PUT /mailerlite/api/forms/{form_id} Content-Type: application/json
{ "name": "Newsletter Signup" } ```
#### 删除表单
```bash DELETE /mailerlite/api/forms/{form_id} ```
#### 获取表单订阅者
```bash GET /mailerlite/api/forms/{form_id}/subscribers ```
查询参数： - `filter[status]` - 按状态筛选：`active`、`unsubscribed`、`unconfirmed`、`bounced`、`junk` - `limit` - 每页结果数（默认：25） - `cursor` - 分页游标
### Webhook 操作
#### 列出 Webhook
```bash GET /mailerlite/api/webhooks ```
#### 获取 Webhook
```bash GET /mailerlite/api/webhooks/{webhook_id} ```
#### 创建 Webhook
```bash POST /mailerlite/api/webhooks Content-Type: application/json
{ "name": "Subscriber Updates", "events": ["subscriber.created", "subscriber.updated"], "url": "https://example.com/webhook" } ```
#### 更新 Webhook
```bash PUT /mailerlite/api/webhooks/{webhook_id} Content-Type: application/json
{ "name": "Updated Webhook", "enabled": true } ```
#### 删除 Webhook
```bash DELETE /mailerlite/api/webhooks/{webhook_id} ```
## 分页
MailerLite 对大多数端点使用基于游标的分页，对某些端点使用基于页面的分页。
### 基于游标的分页
```bash GET /mailerlite/api/subscribers?limit=25&cursor=eyJpZCI6MTIzNDU2fQ ```
响应包含分页链接： ```json { "data": [...], "links": { "first": "https://connect.mailerlite.com/api/subscribers?cursor=...", "last": null, "prev": null, "next": "https://connect.mailerlite.com/api/subscribers?cursor=eyJpZCI6MTIzNDU2fQ" }, "meta": { "path": "https://connect.mailerlite.com/api/subscribers", "per_page": 25, "next_cursor": "eyJpZCI6MTIzNDU2fQ", "prev_cursor": null } } ```
### 基于页面的分页
```bash GET /mailerlite/api/groups?limit=25&page=2 ```
响应包含页面元数据： ```json { "data": [...], "meta": { "current_page": 2, "from": 26, "last_page": 4, "per_page": 25, "to": 50, "total": 100 } } ```
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/mailerlite/api/subscribers?limit=10', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/mailerlite/api/subscribers', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={'limit': 10} ) data = response.json() ```
### 创建订阅者示例
```python import os import requests
response = requests.post( 'https://gateway.maton.ai/mailerlite/api/subscribers', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'email': '[email protected]', 'fields': {'name': 'John Doe'}, 'status': 'active' } ) data = response.json() ```
## 注意事项
- 速率限制：每分钟 120 次请求 - 订阅者电子邮件用作唯一标识符（POST 创建或更新） - 群组名称的最大长度为 255 个字符 - 只有草稿状态的营销活动可以更新 - 可以通过 `X-Version: YYYY-MM-DD` 标头覆盖 API 版本控制 - 重要：使用 curl 命令时，如果 URL 包含方括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递到 `jq` 或其他命令时，在某些 shell 环境中 `$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 MailerLite 连接 | | 401 | Maton API 密钥无效或缺失 | | 403 | 禁止访问 - 权限不足 | | 404 | 未找到资源 | | 422 | 验证错误 | | 429 | 速率受限（120 次/分钟） | | 4xx/5xx | 来自 MailerLite API 的透传错误 |
### 故障排除：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 路径以 `mailerlite` 开头。例如：
- 正确：`https://gateway.maton.ai/mailerlite/api/subscribers` - 错误：`https://gateway.maton.ai/api/subscribers`
## 资源
- [MailerLite API 文档](https://developers.mailerlite.com/docs/) - [MailerLite 订阅者 API](https://developers.mailerlite.com/docs/subscribers.html) - [MailerLite 群组 API](https://developers.mailerlite.com/docs/groups.html) - [MailerLite 营销活动 API](https://developers.mailerlite.com/docs/campaigns.html) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])