Brevo

2026-03-29 新闻来源：网淘吧围观:19

电脑广告

手机广告

Brevo

通过托管的 OAuth 认证访问 Brevo API。发送交易邮件、管理联系人和列表、创建电子邮件营销活动以及使用模板。

快速开始

# 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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

登录或在maton.ai
创建账户前往
maton.ai/settings

复制您的 API 密钥

连接管理在以下地址管理您的 Brevo OAuth 连接：列出连接

创建连接

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

获取连接

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

响应：

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

在浏览器中打开返回的

{
  "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": {}
  }
}

网址以完成 OAuth 授权。删除连接

指定连接

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标头指定要使用的连接：如果省略，网关将使用默认（最早创建的）活动连接。

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 参考

账户

获取账户信息

响应：

GET /brevo/v3/account

联系人

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "companyName": "Acme Inc",
  "relay": {
    "enabled": true,
    "data": {
      "userName": "user@smtp-brevo.com",
      "relay": "smtp-relay.brevo.com",
      "port": 587
    }
  }
}

列出联系人

查询参数：

GET /brevo/v3/contacts

limit

- 每页结果数量（默认：50，最大：500）offset
offset- 首条结果索引（从0开始）
modifiedSince- 按修改日期筛选（ISO 8601格式）

响应：

{
  "contacts": [
    {
      "id": 1,
      "email": "contact@example.com",
      "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
}

获取联系人

GET /brevo/v3/contacts/{identifier}

标识符可以是电子邮件地址、电话号码或联系人ID。

查询参数：

identifierType- 标识符类型：email_id、phone_id、contact_id、ext_id

创建联系人

POST /brevo/v3/contacts
Content-Type: application/json

{
  "email": "newcontact@example.com",
  "attributes": {
    "FIRSTNAME": "Jane",
    "LASTNAME": "Smith"
  },
  "listIds": [2],
  "updateEnabled": false
}

响应：

{
  "id": 2
}

设置updateEnabled: true可在联系人已存在时更新信息。

更新联系人

PUT /brevo/v3/contacts/{identifier}
Content-Type: application/json

{
  "attributes": {
    "FIRSTNAME": "Updated",
    "LASTNAME": "Name"
  }
}

成功时返回204 No Content状态码。

删除联系人

DELETE /brevo/v3/contacts/{identifier}

成功时返回204无内容状态码。

获取联系人营销活动统计

GET /brevo/v3/contacts/{identifier}/campaignStats

列表

列出所有列表

GET /brevo/v3/contacts/lists

响应：

{
  "lists": [
    {
      "id": 2,
      "name": "Newsletter Subscribers",
      "folderId": 1,
      "uniqueSubscribers": 150,
      "totalBlacklisted": 2,
      "totalSubscribers": 148
    }
  ],
  "count": 1
}

获取列表

GET /brevo/v3/contacts/lists/{listId}

创建列表

POST /brevo/v3/contacts/lists
Content-Type: application/json

{
  "name": "New List",
  "folderId": 1
}

响应：

{
  "id": 3
}

更新列表

PUT /brevo/v3/contacts/lists/{listId}
Content-Type: application/json

{
  "name": "Updated List Name"
}

成功时返回204无内容状态码。

删除列表

DELETE /brevo/v3/contacts/lists/{listId}

成功时返回204无内容状态码。

获取列表中的联系人

GET /brevo/v3/contacts/lists/{listId}/contacts

向列表添加联系人

POST /brevo/v3/contacts/lists/{listId}/contacts/add
Content-Type: application/json

{
  "emails": ["contact1@example.com", "contact2@example.com"]
}

从列表中移除联系人

POST /brevo/v3/contacts/lists/{listId}/contacts/remove
Content-Type: application/json

{
  "emails": ["contact1@example.com"]
}

文件夹

列出文件夹

GET /brevo/v3/contacts/folders

响应：

{
  "folders": [
    {
      "id": 1,
      "name": "Marketing",
      "uniqueSubscribers": 500,
      "totalSubscribers": 480,
      "totalBlacklisted": 20
    }
  ],
  "count": 1
}

获取文件夹

GET /brevo/v3/contacts/folders/{folderId}

创建文件夹

POST /brevo/v3/contacts/folders
Content-Type: application/json

{
  "name": "New Folder"
}

响应：

{
  "id": 4
}

更新文件夹

PUT /brevo/v3/contacts/folders/{folderId}
Content-Type: application/json

{
  "name": "Renamed Folder"
}

成功时返回204无内容状态码。

删除文件夹

DELETE /brevo/v3/contacts/folders/{folderId}

删除文件夹及其中的所有列表。成功时返回204 No Content。

获取文件夹中的列表

GET /brevo/v3/contacts/folders/{folderId}/lists

属性

列表属性

GET /brevo/v3/contacts/attributes

响应：

{
  "attributes": [
    {
      "name": "FIRSTNAME",
      "category": "normal",
      "type": "text"
    },
    {
      "name": "LASTNAME",
      "category": "normal",
      "type": "text"
    }
  ]
}

创建属性

POST /brevo/v3/contacts/attributes/{category}/{attributeName}
Content-Type: application/json

{
  "type": "text"
}

类别：普通、事务性、类别、计算型、全局

更新属性

PUT /brevo/v3/contacts/attributes/{category}/{attributeName}
Content-Type: application/json

{
  "value": "new value"
}

删除属性

DELETE /brevo/v3/contacts/attributes/{category}/{attributeName}

事务性邮件

发送邮件

POST /brevo/v3/smtp/email
Content-Type: application/json

{
  "sender": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "to": [
    {
      "email": "recipient@example.com",
      "name": "Jane Smith"
    }
  ],
  "subject": "Welcome!",
  "htmlContent": "<html><body><h1>Hello!</h1><p>Welcome to our service.</p></body></html>"
}

响应：

{
  "messageId": "<202602092329.12910305853@smtp-relay.mailin.fr>"
}

可选参数：

抄送- 抄送收件人
密送- 密件抄送收件人
replyTo- 回复地址
textContent- 纯文本版本
templateId- 使用模板而非htmlContent
params- 模板参数
attachment- 文件附件
headers- 自定义头部
tags- 用于追踪的邮件标签
scheduledAt- 定时发送（ISO 8601格式）

获取事务性邮件

GET /brevo/v3/smtp/emails

查询参数：

email- 按收件人邮箱筛选
templateId- 按模板筛选
messageId- 按消息ID筛选
开始日期- 开始日期（YYYY-MM-DD）
结束日期- 结束日期（YYYY-MM-DD）
限制数量- 每页结果数
偏移量- 起始索引

删除定时邮件

DELETE /brevo/v3/smtp/email/{identifier}

标识符可以是消息ID或批次ID。

获取邮件统计信息

GET /brevo/v3/smtp/statistics/events

查询参数：

限制数量- 每页结果数
偏移量- 起始索引
开始日期- 开始日期
结束日期- 结束日期
电子邮件- 按收件人筛选
事件类型- 按事件类型筛选：已送达,已打开,已点击,已退回, 等。

电子邮件模板

列出模板

GET /brevo/v3/smtp/templates

响应：

{
  "count": 1,
  "templates": [
    {
      "id": 1,
      "name": "Welcome Email",
      "subject": "Welcome {{params.name}}!",
      "isActive": true,
      "sender": {
        "name": "Company",
        "email": "noreply@company.com"
      },
      "htmlContent": "<html>...</html>",
      "createdAt": "2026-02-09 23:29:38",
      "modifiedAt": "2026-02-09 23:29:38"
    }
  ]
}

获取模板

GET /brevo/v3/smtp/templates/{templateId}

创建模板

POST /brevo/v3/smtp/templates
Content-Type: application/json

{
  "sender": {
    "name": "Company",
    "email": "noreply@company.com"
  },
  "templateName": "Welcome Email",
  "subject": "Welcome {{params.name}}!",
  "htmlContent": "<html><body><h1>Hello {{params.name}}!</h1></body></html>"
}

响应：

{
  "id": 1
}

更新模板

PUT /brevo/v3/smtp/templates/{templateId}
Content-Type: application/json

{
  "templateName": "Updated Template Name",
  "subject": "New Subject"
}

成功时返回204 No Content。

删除模板

DELETE /brevo/v3/smtp/templates/{templateId}

成功时返回204 No Content。

发送测试邮件

POST /brevo/v3/smtp/templates/{templateId}/sendTest
Content-Type: application/json

{
  "emailTo": ["test@example.com"]
}

电子邮件营销活动

列出营销活动

GET /brevo/v3/emailCampaigns

查询参数：

类型- 按类型筛选：经典,触发器
状态- 按状态筛选：草稿,已发送,已归档,已排队,已暂停,处理中
限制- 每页结果数
偏移量- 起始索引

响应：

{
  "count": 1,
  "campaigns": [
    {
      "id": 2,
      "name": "Monthly Newsletter",
      "subject": "Our March Update",
      "type": "classic",
      "status": "draft",
      "sender": {
        "name": "Company",
        "email": "news@company.com"
      },
      "createdAt": "2026-02-09T23:29:39.000Z"
    }
  ]
}

获取营销活动

GET /brevo/v3/emailCampaigns/{campaignId}

创建营销活动

POST /brevo/v3/emailCampaigns
Content-Type: application/json

{
  "name": "March Newsletter",
  "subject": "Our March Update",
  "sender": {
    "name": "Company",
    "email": "news@company.com"
  },
  "htmlContent": "<html><body><h1>March News</h1></body></html>",
  "recipients": {
    "listIds": [2]
  }
}

响应：

{
  "id": 2
}

更新营销活动

PUT /brevo/v3/emailCampaigns/{campaignId}
Content-Type: application/json

{
  "name": "Updated Campaign Name",
  "subject": "Updated Subject"
}

成功时返回 204 No Content。

删除营销活动

DELETE /brevo/v3/emailCampaigns/{campaignId}

成功时返回 204 No Content。

立即发送营销活动

POST /brevo/v3/emailCampaigns/{campaignId}/sendNow

发送测试邮件

POST /brevo/v3/emailCampaigns/{campaignId}/sendTest
Content-Type: application/json

{
  "emailTo": ["test@example.com"]
}

更新营销活动状态

PUT /brevo/v3/emailCampaigns/{campaignId}/status
Content-Type: application/json

{
  "status": "suspended"
}

发件人管理

列出发件人

GET /brevo/v3/senders

响应：

{
  "senders": [
    {
      "id": 1,
      "name": "Company",
      "email": "noreply@company.com",
      "active": true,
      "ips": []
    }
  ]
}

获取发件人

GET /brevo/v3/senders/{senderId}

创建发件人

POST /brevo/v3/senders
Content-Type: application/json

{
  "name": "Marketing",
  "email": "marketing@company.com"
}

更新发件人

PUT /brevo/v3/senders/{senderId}
Content-Type: application/json

{
  "name": "Updated Name"
}

删除发件人

DELETE /brevo/v3/senders/{senderId}

已屏蔽联系人

列出已屏蔽联系人

GET /brevo/v3/smtp/blockedContacts

解除屏蔽联系人

DELETE /brevo/v3/smtp/blockedContacts/{email}

已屏蔽域名

列出已屏蔽域名

GET /brevo/v3/smtp/blockedDomains

添加屏蔽域名

POST /brevo/v3/smtp/blockedDomains
Content-Type: application/json

{
  "domain": "spam-domain.com"
}

移除屏蔽域名

DELETE /brevo/v3/smtp/blockedDomains/{domain}

分页功能

Brevo采用基于偏移量的分页机制：

GET /brevo/v3/contacts?limit=50&offset=0

参数：

每页数量限制- 每页返回结果数量（不同接口上限不同，通常最多500条）
偏移量- 起始索引（从0开始计数）

响应包含计数信息：

{
  "contacts": [...],
  "count": 150
}

要获取下一页，将偏移量（offset）增加限制值（limit）：

第 1 页：offset=0&limit=50
第 2 页：offset=50&limit=50
第 3 页：offset=100&limit=50

代码示例

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

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（发送邮件）

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': 'john@example.com'},
        'to': [{'email': 'recipient@example.com', 'name': 'Jane'}],
        'subject': 'Hello!',
        'htmlContent': '<html><body><h1>Hi Jane!</h1></body></html>'
    }
)
result = response.json()
print(f"Sent! Message ID: {result['messageId']}")

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': 'newuser@example.com',
        '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或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开

错误处理

状态码	含义
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 密钥"错误时，在断定存在问题之前，请始终遵循以下步骤：

检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

通过列出连接来验证 API 密钥是否有效：

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

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：ClickSend 下一篇：Home Assistant CLI