Brevo 邮件营销 API

通过 Brevo 的 REST API 管理联系人、发送邮件并自动化营销。

身份验证

bash
BREVOKEY=$(cat ~/.config/brevo/apikey)

所有请求都需要包含请求头：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: user@example.com,
listIds: [10],
updateEnabled: true,
attributes: {
NOMBRE: John,
APELLIDOS: Doe
}
}

获取联系人信息

bash
curl https://api.brevo.com/v3/contacts/user@example.com \
-H api-key: $BREVO_KEY

更新联系人属性

bash
curl -X PUT https://api.brevo.com/v3/contacts/user@example.com \
-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: noreply@example.com},
to: [{email: user@example.com, name: John}],
subject: Welcome!,
htmlContent:

Hello {{params.name}}

,
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: user@example.com}],
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: [user1@example.com, user2@example.com]
}

安全导入模式

导入联系人时，始终尊重退订：

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():
获取所有退订/黑名单邮件
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 safeimport(emails, listid):
导入联系人，尊重退订
blacklisted = get_blacklisted()

for email in emails:
if email.lower() in blacklisted:
print(f已跳过（已退订）：{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已导入：{email})
else:
print(f错误：{email} - {r.text[:50]})

联系人属性

Brevo 使用自定义属性存储联系人数据：

json
{
attributes: {
NOMBRE: John,
APELLIDOS: Doe,
FECHA_ALTA: 2026-01-15,
PLAN: premium,
CUSTOM_FIELD: any value
}
}

在 Brevo 控制面板中创建属性：联系人 → 设置 → 联系人属性。

响应代码

代码	含义
200	成功（GET）
201

已创建（POST） | | 204 | 成功，无内容（PUT/DELETE） | | 400 | 错误请求（检查请求体） | | 401 | 无效 API 密钥 | | 404 | 联系人/资源未找到 |

最佳实践

1. 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: user@example.com, attributes: {NOMBRE: John}}
]
}

实用查询

bash

统计列表中的联系人数量

curl https://api.brevo.com/v3/contacts/lists/10 -H api-key: $BREVO_KEY | jq .totalSubscribers

获取最近的联系人

curl https://api.brevo.com/v3/contacts?limit=10&sort=desc -H api-key: $BREVO_KEY

检查邮箱是否存在

curl https://api.brevo.com/v3/contacts/user@example.com -H api-key: $BREVO_KEY

获取账户信息

curl https://api.brevo.com/v3/account -H api-key: $BREVO_KEY