Brevo 连接器
Brevo 连接器
将您的 Brevo 账户连接到 Tajo，实现统一的联系人管理、跨邮件/短信/WhatsApp 的交易消息发送以及全面的营销自动化。
概览
| 属性 | 值 |
|---|---|
| 平台 | Brevo |
| 类别 | 营销 |
| 设置复杂度 | 简单 |
| 官方集成 | 是 |
| 同步数据 | 联系人、营销活动、交易消息、事件、电子商务 |
| API 基础 URL | https://api.brevo.com/v3 |
功能
- 多渠道消息 - 通过统一 API 发送交易邮件、短信和 WhatsApp 消息
- 联系人管理 - 使用自定义属性创建、更新和细分联系人
- 营销活动 - 以编程方式创建和发送邮件营销活动
- 事件跟踪 - 通过 Brevo Tracker 跟踪自定义事件和网站活动
- 电子商务同步 - 同步产品、订单和购物车数据，用于个性化营销活动
- 忠诚度计划 - 管理忠诚度订阅、积分和会员数据
- Webhook 支持 - 交易、营销和 CRM 事件的实时通知
- 对话 - 实时聊天小部件集成和程序化消息管理
前提条件
开始之前，请确保您已具备：
- Brevo 账户（免费、入门、商业或企业计划）
- 从 Brevo 设置 > API 密钥生成的 API 密钥
- 具有 API 访问权限的 Tajo 账户
- 已验证的发件人域名（用于邮件发送）
认证
Brevo 支持两种认证方式：
API 密钥认证（推荐）
在每次请求的 api-key 请求头中包含您的 API 密钥。最适合直接集成和服务器间通信。
curl -X GET "https://api.brevo.com/v3/account" \ -H "api-key: YOUR_API_KEY" \ -H "Content-Type: application/json"OAuth 2.0 认证
对于需要委托访问和用户特定权限的组织内私人集成，使用 OAuth 2.0。OAuth 提供具有定义有效期的基于令牌的系统。
OAuth 可用性
OAuth 目前仅适用于组织内的私人集成。OAuth 集成不适合公开分发或市场上架。
配置
基础设置
connectors: brevo: enabled: true api_key: "${BREVO_API_KEY}" api_version: "v3"
# Data sync options sync: contacts: true campaigns: true transactional: true events: true ecommerce: true
# List assignment lists: all_customers: 5 newsletter: 6 buyers: 7字段映射
将您的数据字段映射到 Brevo 联系人属性：
默认映射
| Parameter | Type | Description |
|---|---|---|
email required | string | 联系人邮箱地址（唯一标识符） |
FIRSTNAME optional | string | 联系人名字属性 |
LASTNAME optional | string | 联系人姓氏属性 |
SMS optional | string | 用于短信和 WhatsApp 消息的电话号码 |
OPT_IN optional | boolean | 营销选择加入同意状态 |
ORDER_COUNT optional | integer | 已下单总数 |
TOTAL_REVENUE optional | number | 该联系人的终身收入 |
LOYALTY_POINTS optional | integer | 当前忠诚度计划积分余额 |
自定义属性映射
field_mapping: # Standard fields email: email first_name: FIRSTNAME last_name: LASTNAME phone: SMS
# Marketing fields opt_in: OPT_IN signup_source: SIGNUP_SOURCE preferred_language: LANGUAGE
# eCommerce metrics orders_count: ORDER_COUNT total_spent: TOTAL_REVENUE last_order_date: LAST_ORDER_DATE
# Loyalty fields loyalty_tier: VIP_TIER loyalty_points: LOYALTY_POINTSAPI 端点
核心端点
| 方法 | 端点 | 描述 |
|---|---|---|
POST | /v3/smtp/email | 发送交易邮件 |
POST | /v3/transactionalSMS/send | 发送交易短信 |
POST | /v3/whatsapp/sendMessage | 发送交易 WhatsApp 消息 |
POST | /v3/contacts | 创建联系人 |
PUT | /v3/contacts/{email} | 更新联系人 |
GET | /v3/contacts/{identifier} | 获取联系人详情 |
POST | /v3/contacts/import | 批量导入联系人 |
电子商务端点
| 方法 | 端点 | 描述 |
|---|---|---|
POST | /v3/orders/status | 创建或更新订单状态 |
POST | /v3/products | 创建或更新产品 |
POST | /v3/categories | 创建或更新产品类别 |
POST | /v3/events | 跟踪自定义事件 |
营销活动端点
| 方法 | 端点 | 描述 |
|---|---|---|
POST | /v3/emailCampaigns | 创建邮件营销活动 |
POST | /v3/emailCampaigns/{id}/sendNow | 立即发送营销活动 |
GET | /v3/emailCampaigns | 列出所有邮件营销活动 |
GET | /v3/smtp/statistics/events | 获取邮件事件统计 |
事件
交易事件
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
delivered | 邮件已送达收件箱 | 投递确认 |
opened | 收件人打开邮件 | 参与度跟踪 |
clicked | 点击邮件中的链接 | 点击跟踪 |
bounced | 邮件退回 | 列表清洗 |
spam | 标记为垃圾邮件 | 合规监控 |
unsubscribed | 联系人退订 | 偏好管理 |
电子商务事件
| 事件 | 触发条件 | 使用场景 |
|---|---|---|
order_completed | 订单成功下单 | 购买后流程 |
cart_updated | 购物车内容变更 | 放弃购物车跟踪 |
cart_deleted | 购物车清空或过期 | 购物车召回 |
product_viewed | 访问产品页面 | 浏览放弃跟踪 |
代码示例
初始化连接器
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Connect Brevo accountawait tajo.connectors.connect('brevo', { apiKey: process.env.BREVO_API_KEY});发送交易邮件
// Send a transactional email via Brevoawait tajo.brevo.sendTransactionalEmail({ templateId: 12, params: { ORDER_ID: '12345', ORDER_TOTAL: '$59.99', DELIVERY_DATE: '2024-02-15' }});同步联系人
// Bulk import contacts to Brevoawait tajo.connectors.sync('brevo', { type: 'full', resources: ['contacts'], options: { listIds: [5, 6], updateExisting: true, emptyContactsAttributes: false }});
// Check sync statusconst status = await tajo.connectors.status('brevo');console.log(status);// {// connected: true,// lastSync: '2024-01-15T10:30:00Z',// contactsSynced: 25400,// campaignsSent: 142,// eventsTracked: 89320// }跟踪自定义事件
// Track a custom event for a contactawait tajo.brevo.trackEvent({ event: 'product_purchased', eventdata: { id: 'txn_98765', data: { product_name: 'Premium Widget', price: 49.99, currency: 'USD' } }});速率限制
Brevo 根据您的计划对三个层级实施速率限制：
| 端点 | 免费/入门版 | 专业版 | 企业版 |
|---|---|---|---|
POST /v3/smtp/email | 1,000 RPS | 2,000 RPS | 6,000 RPS |
POST /v3/transactionalSMS/send | 150 RPS | 200 RPS | 250 RPS |
POST /v3/events | 10 RPS | 20 RPS | 60 RPS |
/v3/contacts/* | 10 RPS | 20 RPS | 60 RPS |
| 所有其他端点 | 100 RPH | 200 RPH | 600 RPH |
速率限制响应
超出速率限制时，API 返回 429 Too Many Requests 状态码。监控响应中的速率限制响应头以跟踪使用情况。
故障排除
常见问题
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 401 Unauthorized | API 密钥无效 | 在 Brevo 设置中重新生成 API 密钥 |
| 联系人未创建 | 缺少邮箱字段 | 确保为所有联系人提供邮箱 |
| 邮件未送达 | 发件人域名未验证 | 在 Brevo 发件人设置中验证域名 |
| 未收到 Webhook | URL 错误或服务器错误 | 检查 Webhook URL 可访问性和日志 |
| 短信未发送 | 电话号码格式无效 | 使用带国家代码的国际格式 |
调试模式
启用详细日志记录：
connectors: brevo: debug: true log_level: verbose log_webhooks: true测试连接
tajo connectors test brevo# ✓ API connection successful# ✓ Contacts API accessible# ✓ Transactional email ready# ✓ SMS sending configured# ✓ Webhooks registered最佳实践
- 使用 API 密钥轮换 - 定期轮换 API 密钥以确保安全
- 实施 Webhook 验证 - 使用用户名/密码认证验证 Webhook 签名
- 批量导入联系人 - 对大型数据集使用批量导入，而非单个 API 调用
- 监控速率限制 - 检查速率限制响应头，避免 429 错误
- 使用事件跟踪 - 实施 Brevo Tracker，获取全面的客户行为数据
- 设置适当的发件人认证 - 配置 SPF、DKIM 和 DMARC，以获得最佳投递率
安全
- API 密钥认证 - 通过
api-key请求头进行基于密钥的访问 - OAuth 2.0 - 私人集成的基于令牌的委托访问
- Webhook 验证 - 安全 Webhook 调用的用户名和密码认证
- TLS 加密 - 所有 API 通信在传输中加密
- IP 白名单 - 企业计划可选 IP 限制