介绍
# Brevo
通过托管 OAuth 身份验证访问 Brevo API。发送事务性电子邮件、管理联系人和列表、创建电子邮件营销活动以及使用模板。
## 快速开始
```bash # Get account info python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/brevo/v3/account') 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/brevo/v3/{resource} ```
网关将请求代理到 `api.brevo.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` 管理您的 Brevo OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=brevo&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': 'brevo'}).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": "b04dd695-d056-433b-baf9-0fb4eb3bde9e", "status": "ACTIVE", "creation_time": "2026-02-09T19:51:00.932629Z", "last_updated_time": "2026-02-09T19:51:30.123456Z", "url": "https://connect.maton.ai/?session_token=...", "app": "brevo", "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 ```
### 指定连接
如果您有多个 Brevo 连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/brevo/v3/account') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', 'b04dd695-d056-433b-baf9-0fb4eb3bde9e') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 账户
#### 获取账户信息
```bash GET /brevo/v3/account ```
**响应：** ```json { "email": "[email protected]", "firstName": "John", "lastName": "Doe", "companyName": "Acme Inc", "relay": { "enabled": true, "data": { "userName": "[email protected]", "relay": "smtp-relay.brevo.com", "port": 587 } } } ```
### 联系人
#### 列出联系人
```bash GET /brevo/v3/contacts ```
**查询参数：** - `limit` - 每页结果数（默认：50，最大：500） - `offset` - 第一个结果的索引（从 0 开始） - `modifiedSince` - 按修改日期筛选（ISO 8601）
**响应：** ```json { "contacts": [ { "id": 1, "email": "[email protected]", "emailBlacklisted": false, "smsBlacklisted": false, "createdAt": "2026-02-09T20:33:59.705+01:00", "modifiedAt": "2026-02-09T20:35:19.529+01:00", "listIds": [2], "attributes": { "FIRSTNAME": "John", "LASTNAME": "Doe" } } ], "count": 1 } ```
#### 获取联系人
```bash GET /brevo/v3/contacts/{identifier} ```
标识符可以是电子邮件地址、电话号码或联系人 ID。
**查询参数：** - `identifierType` - 标识符类型：`email_id`、`phone_id`、`contact_id`、`ext_id`
#### 创建联系人
```bash POST /brevo/v3/contacts Content-Type: application/json
{ "email": "[email protected]", "attributes": { "FIRSTNAME": "Jane", "LASTNAME": "Smith" }, "listIds": [2], "updateEnabled": false } ```
**响应：** ```json { "id": 2 } ```
设置 `updateEnabled: true` 可在联系人已存在时更新该联系人。
#### 更新联系人
```bash PUT /brevo/v3/contacts/{identifier} Content-Type: application/json
{ "attributes": { "FIRSTNAME": "Updated", "LASTNAME": "Name" } } ```
成功时返回 204 No Content。
#### 删除联系人
```bash DELETE /brevo/v3/contacts/{identifier} ```
成功时返回 204 No Content。
#### 获取联系人营销活动统计
```bash GET /brevo/v3/contacts/{identifier}/campaignStats ```
### 列表
#### 列出所有列表
```bash GET /brevo/v3/contacts/lists ```
**响应：** ```json { "lists": [ { "id": 2, "name": "Newsletter Subscribers", "folderId": 1, "uniqueSubscribers": 150, "totalBlacklisted": 2, "totalSubscribers": 148 } ], "count": 1 } ```
#### 获取列表
```bash GET /brevo/v3/contacts/lists/{listId} ```
#### 创建列表
```bash POST /brevo/v3/contacts/lists Content-Type: application/json
{ "name": "New List", "folderId": 1 } ```
**响应：** ```json { "id": 3 } ```
#### 更新列表
```bash PUT /brevo/v3/contacts/lists/{listId} Content-Type: application/json
{ "name": "Updated List Name" } ```
成功时返回 204 No Content。
#### 删除列表
```bash DELETE /brevo/v3/contacts/lists/{listId} ```
成功时返回 204 No Content。
#### 获取列表中的联系人
```bash GET /brevo/v3/contacts/lists/{listId}/contacts ```
#### 向列表添加联系人
```bash POST /brevo/v3/contacts/lists/{listId}/contacts/add Content-Type: application/json
{ "emails": ["[email protected]", "[email protected]"] } ```
#### 从列表移除联系人
```bash POST /brevo/v3/contacts/lists/{listId}/contacts/remove Content-Type: application/json
{ "emails": ["[email protected]"] } ```
### 文件夹
#### 列出文件夹
```bash GET /brevo/v3/contacts/folders ```
**响应：** ```json { "folders": [ { "id": 1, "name": "Marketing", "uniqueSubscribers": 500, "totalSubscribers": 480, "totalBlacklisted": 20 } ], "count": 1 } ```
#### 获取文件夹
```bash GET /brevo/v3/contacts/folders/{folderId} ```
#### 创建文件夹
```bash POST /brevo/v3/contacts/folders Content-Type: application/json
{ "name": "New Folder" } ```
**响应：** ```json { "id": 4 } ```
#### 更新文件夹
```bash PUT /brevo/v3/contacts/folders/{folderId} Content-Type: application/json
{ "name": "Renamed Folder" } ```
成功时返回 204 No Content。
#### 删除文件夹
```bash DELETE /brevo/v3/contacts/folders/{folderId} ```
删除文件夹及其中的所有列表。成功时返回 204 No Content。
#### 获取文件夹中的列表
```bash GET /brevo/v3/contacts/folders/{folderId}/lists ```
### 属性
#### 列出属性
```bash GET /brevo/v3/contacts/attributes ```
**响应：** ```json { "attributes": [ { "name": "FIRSTNAME", "category": "normal", "type": "text" }, { "name": "LASTNAME", "category": "normal", "type": "text" } ] } ```
#### 创建属性
```bash POST /brevo/v3/contacts/attributes/{category}/{attributeName} Content-Type: application/json
{ "type": "text" } ```
类别：`normal`、`transactional`、`category`、`calculated`、`global`
#### 更新属性
```bash PUT /brevo/v3/contacts/attributes/{category}/{attributeName} Content-Type: application/json
{ "value": "new value" } ```
#### 删除属性
```bash DELETE /brevo/v3/contacts/attributes/{category}/{attributeName} ```
### 事务性邮件
#### 发送邮件
```bash POST /brevo/v3/smtp/email Content-Type: application/json
{ "sender": { "name": "John Doe", "email": "[email protected]" }, "to": [ { "email": "[email protected]", "name": "Jane Smith" } ], "subject": "Welcome!", "htmlContent": "<html><body><h1>Hello!</h1><p>Welcome to our service.</p></body></html>" } ```
**响应：** ```json { "messageId": "<[email protected]>" } ```
**可选参数：** - `cc` - 抄送收件人 - `bcc` - 密送收件人 - `replyTo` - 回复地址 - `textContent` - 纯文本版本 - `templateId` - 使用模板代替 htmlContent - `params` - 模板参数 - `attachment` - 文件附件 - `headers` - 自定义标头 - `tags` - 用于跟踪的邮件标签 - `scheduledAt` - 定时发送（ISO 8601）
#### 获取事务性邮件
```bash GET /brevo/v3/smtp/emails ```
**查询参数：** - `email` - 按收件人邮件筛选 - `templateId` - 按模板筛选 - `messageId` - 按消息 ID 筛选 - `startDate` - 开始日期（YYYY-MM-DD） - `endDate` - 结束日期（YYYY-MM-DD） - `limit` - 每页结果数 - `offset` - 起始索引
#### 删除定时邮件
```bash DELETE /brevo/v3/smtp/email/{identifier} ```
标识符可以是 messageId 或 batchId。
#### 获取邮件统计
```bash GET /brevo/v3/smtp/statistics/events ```
**查询参数：** - `limit` - 每页结果数 - `offset` - 起始索引 - `startDate` - 开始日期 - `endDate` - 结束日期 - `email` - 按收件人筛选 - `event` - 按事件类型筛选：`delivered`（已送达）、`opened`（已打开）、`clicked`（已点击）、`bounced`（退信）等。
### 邮件模板
#### 列出模板
```bash GET /brevo/v3/smtp/templates ```
**响应：** ```json { "count": 1, "templates": [ { "id": 1, "name": "Welcome Email", "subject": "Welcome {{params.name}}!", "isActive": true, "sender": { "name": "Company", "email": "[email protected]" }, "htmlContent": "<html>...</html>", "createdAt": "2026-02-09 23:29:38", "modifiedAt": "2026-02-09 23:29:38" } ] } ```
#### 获取模板
```bash GET /brevo/v3/smtp/templates/{templateId} ```
#### 创建模板
```bash POST /brevo/v3/smtp/templates Content-Type: application/json
{ "sender": { "name": "Company", "email": "[email protected]" }, "templateName": "Welcome Email", "subject": "Welcome {{params.name}}!", "htmlContent": "<html><body><h1>Hello {{params.name}}!</h1></body></html>" } ```
**响应：** ```json { "id": 1 } ```
#### 更新模板
```bash PUT /brevo/v3/smtp/templates/{templateId} Content-Type: application/json
{ "templateName": "Updated Template Name", "subject": "New Subject" } ```
成功时返回 204 No Content。
#### 删除模板
```bash DELETE /brevo/v3/smtp/templates/{templateId} ```
成功时返回 204 No Content。
#### 发送测试邮件
```bash POST /brevo/v3/smtp/templates/{templateId}/sendTest Content-Type: application/json
{ "emailTo": ["[email protected]"] } ```
### 邮件营销活动
#### 列出营销活动
```bash GET /brevo/v3/emailCampaigns ```
**查询参数：** - `type` - 按类型筛选：`classic`（经典）、`trigger`（触发） - `status` - 按状态筛选：`draft`（草稿）、`sent`（已发送）、`archive`（归档）、`queued`（排队中）、`suspended`（暂停）、`in_process`（处理中） - `limit` - 每页结果数 - `offset` - 起始索引
**响应：** ```json { "count": 1, "campaigns": [ { "id": 2, "name": "Monthly Newsletter", "subject": "Our March Update", "type": "classic", "status": "draft", "sender": { "name": "Company", "email": "[email protected]" }, "createdAt": "2026-02-09T23:29:39.000Z" } ] } ```
#### 获取营销活动
```bash GET /brevo/v3/emailCampaigns/{campaignId} ```
#### 创建营销活动
```bash POST /brevo/v3/emailCampaigns Content-Type: application/json
{ "name": "March Newsletter", "subject": "Our March Update", "sender": { "name": "Company", "email": "[email protected]" }, "htmlContent": "<html><body><h1>March News</h1></body></html>", "recipients": { "listIds": [2] } } ```
**响应：** ```json { "id": 2 } ```
#### 更新营销活动
```bash PUT /brevo/v3/emailCampaigns/{campaignId} Content-Type: application/json
{ "name": "Updated Campaign Name", "subject": "Updated Subject" } ```
成功时返回 204 No Content。
#### 删除营销活动
```bash DELETE /brevo/v3/emailCampaigns/{campaignId} ```
成功时返回 204 No Content。
#### 立即发送营销活动
```bash POST /brevo/v3/emailCampaigns/{campaignId}/sendNow ```
#### 发送测试邮件
```bash POST /brevo/v3/emailCampaigns/{campaignId}/sendTest Content-Type: application/json
{ "emailTo": ["[email protected]"] } ```
#### 更新营销活动状态
```bash PUT /brevo/v3/emailCampaigns/{campaignId}/status Content-Type: application/json
{ "status": "suspended" } ```
### 发件人
#### 列出发件人
```bash GET /brevo/v3/senders ```
**响应：** ```json { "senders": [ { "id": 1, "name": "Company", "email": "[email protected]", "active": true, "ips": [] } ] } ```
#### 获取发件人
```bash GET /brevo/v3/senders/{senderId} ```
#### 创建发件人
```bash POST /brevo/v3/senders Content-Type: application/json
{ "name": "Marketing", "email": "[email protected]" } ```
#### 更新发件人
```bash PUT /brevo/v3/senders/{senderId} Content-Type: application/json
{ "name": "Updated Name" } ```
#### 删除发件人
```bash DELETE /brevo/v3/senders/{senderId} ```
### 受阻联系人
#### 列出受阻联系人
```bash GET /brevo/v3/smtp/blockedContacts ```
#### 解除联系人阻止
```bash DELETE /brevo/v3/smtp/blockedContacts/{email} ```
### 受阻域名
#### 列出受阻域名
```bash GET /brevo/v3/smtp/blockedDomains ```
#### 添加受阻域名
```bash POST /brevo/v3/smtp/blockedDomains Content-Type: application/json
{ "domain": "spam-domain.com" } ```
#### 移除受阻域名
```bash DELETE /brevo/v3/smtp/blockedDomains/{domain} ```
## 分页
Brevo 使用基于偏移量的分页：
```bash GET /brevo/v3/contacts?limit=50&offset=0 ```
**参数：** - `limit` - 每页结果数（因端点而异，通常最大为 500） - `offset` - 起始索引（从 0 开始）
**响应包含计数：** ```json { "contacts": [...], "count": 150 } ```
要获取下一页，请将 offset 增加 limit： - 第 1 页：`offset=0&limit=50` - 第 2 页：`offset=50&limit=50` - 第 3 页：`offset=100&limit=50`
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/brevo/v3/contacts', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); console.log(data.contacts); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/brevo/v3/contacts', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() print(data['contacts']) ```
### Python (发送邮件)
```python import os import requests
response = requests.post( 'https://gateway.maton.ai/brevo/v3/smtp/email', headers={ 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }, json={ 'sender': {'name': 'John', 'email': '[email protected]'}, 'to': [{'email': '[email protected]', 'name': 'Jane'}], 'subject': 'Hello!', 'htmlContent': '<html><body><h1>Hi Jane!</h1></body></html>' } ) result = response.json() print(f"Sent! Message ID: {result['messageId']}") ```
### Python (创建联系人并添加到列表)
```python import os import requests
headers = { 'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}', 'Content-Type': 'application/json' }
# Create contact response = requests.post( 'https://gateway.maton.ai/brevo/v3/contacts', headers=headers, json={ 'email': '[email protected]', 'attributes': {'FIRSTNAME': 'New', 'LASTNAME': 'User'}, 'listIds': [2] } ) contact = response.json() print(f"Created contact ID: {contact['id']}") ```
## 注意事项
- 所有端点都需要路径中的 `/v3/` 前缀 - 属性名称必须使用大写字母 - 联系人标识符可以是电子邮件、电话号码或 ID - 发件人电子邮件地址必须在 Brevo 中经过验证 - 模板参数使用 `{{params.name}}` 语法 - PUT 和 DELETE 操作成功时返回 204 No Content - 速率限制：免费计划为 300 次/分钟，付费计划更高 - 重要提示：当通过管道将 curl 输出传递给 `jq` 或其他命令时，某些 Shell 环境中可能无法正确展开像 `$MATON_API_KEY` 这样的环境变量
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Brevo 连接或请求错误 | | 401 | Maton API 密钥无效或缺失 | | 404 | 未找到资源 | | 429 | 速率受限 | | 4xx/5xx | 来自 Brevo API 的透传错误 |
响应中的速率限制标头： - `x-sib-ratelimit-limit` - 请求限制 - `x-sib-ratelimit-remaining` - 剩余请求数 - `x-sib-ratelimit-reset` - 重置时间
### 故障排查：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 ```
## 资源
- [Brevo API 概述](https://developers.brevo.com/) - [Brevo API 核心概念](https://developers.brevo.com/docs/how-it-works) - [Brevo OAuth 2.0](https://developers.brevo.com/docs/integrating-oauth-20-to-your-solution) - [管理联系人](https://developers.brevo.com/docs/synchronise-contact-lists) - [发送事务性邮件](https://developers.brevo.com/docs/send-a-transactional-email)