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": "Welcome!",
    "htmlContent": "<p>Hello {{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():
    """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使用自定义属性存储联系人数据：

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

实用查询

# 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/user@example.com" -H "api-key: $BREVO_KEY"

# Get account info
curl "https://api.brevo.com/v3/account" -H "api-key: $BREVO_KEY"