介绍
# Brevo Email Marketing API
通过 Brevo 的 REST API 管理联系人、发送电子邮件并实现营销自动化。
## 认证
```bash BREVO_KEY=$(cat ~/.config/brevo/api_key) ```
所有请求都需要请求头：`api-key: $BREVO_KEY`
## 基础 URL
``` https://api.brevo.com/v3 ```
## 常用端点
### 联系人
| 操作 | 方法 | 端点 | |--------|--------|----------| | 创建联系人 | POST | `/contacts` | | 获取联系人 | GET | `/contacts/{email}` | | 更新联系人 | PUT | `/contacts/{email}` | | 删除联系人 | DELETE | `/contacts/{email}` | | 列出联系人 | GET | `/contacts?limit=50&offset=0` | | 获取黑名单 | GET | `/contacts?emailBlacklisted=true` |
### 列表
| 操作 | 方法 | 端点 | |--------|--------|----------| | 获取所有列表 | GET | `/contacts/lists` | | 创建列表 | POST | `/contacts/lists` | | 获取列表联系人 | GET | `/contacts/lists/{listId}/contacts` | | 添加到列表 | POST | `/contacts/lists/{listId}/contacts/add` | | 从列表中移除 | POST | `/contacts/lists/{listId}/contacts/remove` |
### 邮件
| 操作 | 方法 | 端点 | |--------|--------|----------| | 发送事务邮件 | POST | `/smtp/email` | | 发送营销活动 | POST | `/emailCampaigns` | | 获取模板 | GET | `/smtp/templates` |
## 示例
### 创建/更新联系人
```bash curl -X POST "https://api.brevo.com/v3/contacts" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "[email protected]", "listIds": [10], "updateEnabled": true, "attributes": { "NOMBRE": "John", "APELLIDOS": "Doe" } }' ```
### 获取联系人信息
```bash curl "https://api.brevo.com/v3/contacts/[email protected]" \ -H "api-key: $BREVO_KEY" ```
### 更新联系人属性
```bash curl -X PUT "https://api.brevo.com/v3/contacts/[email protected]" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "listIds": [10, 15], "attributes": { "CUSTOM_FIELD": "value" } }' ```
### 发送事务邮件
```bash curl -X POST "https://api.brevo.com/v3/smtp/email" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "sender": {"name": "My App", "email": "[email protected]"}, "to": [{"email": "[email protected]", "name": "John"}], "subject": "Welcome!", "htmlContent": "<p>Hello {{params.name}}</p>", "params": {"name": "John"} }' ```
### 使用模板发送
```bash curl -X POST "https://api.brevo.com/v3/smtp/email" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": [{"email": "[email protected]"}], "templateId": 34, "params": { "NOMBRE": "John", "FECHA": "2026-02-01" } }' ```
### 列出所有联系人列表
```bash curl "https://api.brevo.com/v3/contacts/lists?limit=50" \ -H "api-key: $BREVO_KEY" ```
### 将联系人添加到列表（批量）
```bash curl -X POST "https://api.brevo.com/v3/contacts/lists/10/contacts/add" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "emails": ["[email protected]", "[email protected]"] }' ```
## 安全导入模式
导入联系人时，**务必尊重取消订阅操作**：
```python import requests
BREVO_KEY = "your-api-key" HEADERS = {'api-key': BREVO_KEY, 'Content-Type': 'application/json'} BASE = 'https://api.brevo.com/v3'
def get_blacklisted(): """Get all unsubscribed/blacklisted emails""" blacklisted = set() offset = 0 while True: r = requests.get( f'{BASE}/contacts?limit=100&offset={offset}&emailBlacklisted=true', headers=HEADERS ) contacts = r.json().get('contacts', []) if not contacts: break for c in contacts: blacklisted.add(c['email'].lower()) offset += 100 return blacklisted
def safe_import(emails, list_id): """Import contacts respecting unsubscribes""" blacklisted = get_blacklisted() for email in emails: if email.lower() in blacklisted: print(f"Skipped (unsubscribed): {email}") continue r = requests.post(f'{BASE}/contacts', headers=HEADERS, json={ 'email': email, 'listIds': [list_id], 'updateEnabled': True }) if r.status_code in [200, 201, 204]: print(f"Imported: {email}") else: print(f"Error: {email} - {r.text[:50]}") ```
## 联系人属性
Brevo 使用自定义属性存储联系人数据：
```json { "attributes": { "NOMBRE": "John", "APELLIDOS": "Doe", "FECHA_ALTA": "2026-01-15", "PLAN": "premium", "CUSTOM_FIELD": "any value" } } ```
在 Brevo 仪表板中创建属性：Contacts → Settings → Contact attributes。
## 响应代码
| 代码 | 含义 | |------|---------| | 200 | 成功 (GET) | | 201 | 已创建 (POST) | | 204 | 成功，无内容 (PUT/DELETE) | | 400 | 错误的请求 (检查 payload) | | 401 | 无效的 API 密钥 | | 404 | 未找到联系人/资源 |
## 最佳实践
1. 导入联系人前**务必检查黑名单** 2. **使用 `updateEnabled: true`** 更新现有联系人而不是失败 3. **使用模板** 发送一致的事务邮件 4. 将许多联系人添加到列表时使用**批量操作** 5. 将列表 ID **存储在配置中**，不要硬编码 6. **记录导入** 操作以便进行审计追踪
## 自动化
Brevo 自动化在以下情况下触发： - 联系人添加到列表 - 联系人属性已更新 - 邮件已打开/已点击 - 通过 API 发送的自定义事件
手动触发自动化： ```bash curl -X POST "https://api.brevo.com/v3/contacts/import" \ -H "api-key: $BREVO_KEY" \ -H "Content-Type: application/json" \ -d '{ "listIds": [10], "emailBlacklist": false, "updateExistingContacts": true, "emptyContactsAttributes": false, "jsonBody": [ {"email": "[email protected]", "attributes": {"NOMBRE": "John"}} ] }' ```
## 有用查询
```bash # Count contacts in list curl "https://api.brevo.com/v3/contacts/lists/10" -H "api-key: $BREVO_KEY" | jq '.totalSubscribers'
# Get recent contacts curl "https://api.brevo.com/v3/contacts?limit=10&sort=desc" -H "api-key: $BREVO_KEY"
# Check if email exists curl "https://api.brevo.com/v3/contacts/[email protected]" -H "api-key: $BREVO_KEY"
# Get account info curl "https://api.brevo.com/v3/account" -H "api-key: $BREVO_KEY" ```