名称： brevo
版本： 1.0.0
描述： Brevo（原 Sendinblue）电子邮件营销 API，用于管理联系人、列表、发送事务性邮件和营销活动。适用于导入联系人、发送邮件、管理订阅或处理邮件自动化。

Brevo 电子邮件营销 API

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

认证

BREVO_KEY=$(cat ~/.config/brevo/api_key)

所有请求都需要在请求头中包含：api-key: $BREVO_KEY

基础 URL

https://api.brevo.com/v3

常用端点

联系人

列表

邮件

示例

创建/更新联系人

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"
    }
  }'

获取联系人信息

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

更新联系人属性

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"
    }
  }'

发送事务性邮件

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": "欢迎！",
    "htmlContent": "<p>你好 {{params.name}}</p>",
    "params": {"name": "John"}
  }'

使用模板发送邮件

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"
    }
  }'

列出所有联系人列表

curl "https://api.brevo.com/v3/contacts/lists?limit=50" \
  -H "api-key: $BREVO_KEY"

批量添加联系人到列表

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"]
  }'

安全导入模式

导入联系人时，务必尊重退订状态：

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 safe_import(emails, list_id):
    """导入联系人，同时尊重退订状态"""
    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 使用自定义属性存储联系人数据：

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

在 Brevo 仪表板中创建属性：联系人 → 设置 → 联系人属性。

响应码

最佳实践

1. 始终检查黑名单：在导入联系人之前
2. 使用 updateEnabled: true：更新现有联系人而非失败
3. 使用模板：确保事务性邮件的一致性
4. 批量操作：当需要添加大量联系人到列表时
5. 存储列表 ID：在配置中而非硬编码
6. 记录导入日志：便于审计追踪

自动化

Brevo 自动化可在以下情况下触发：
- 联系人被添加到列表
- 联系人属性更新
- 邮件被打开/点击
- 通过 API 发送的自定义事件

手动触发自动化：

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"}}
    ]
  }'

实用查询

# 统计列表中的联系人数量
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"