---
title: "Brevo 连接器"
description: "完整的 Brevo 集成指南，通过 Tajo 同步联系人、交易电子邮件、短信、WhatsApp 营销活动和营销自动化。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/brevo/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/brevo.md
lang: zh-CN
robots: noindex
---

申请抢先体验

请输入您的名字和公司电子邮箱地址。我们会发送确认 Tajo 访问申请的链接。

# Brevo 连接器

连接器状态: 已上线 已验证。Tajo 目前运行此连接器。

| 来源字段 | 目标字段 | 示例值 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

将您的 Brevo 账户连接到 Tajo，实现统一的联系人管理、跨邮件/短信/WhatsApp 的交易消息发送以及全面的营销自动化。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Brevo |
| **类别** | 营销 |
| **设置复杂度** | 简单 |
| **官方集成** | 是 |
| **同步数据** | 联系人、营销活动、交易消息、事件、电子商务 |
| **API 基础 URL** | `https://api.brevo.com/v3` |

## 功能

- **多渠道消息** - 通过统一 API 发送交易邮件、短信和 WhatsApp 消息
- **联系人管理** - 使用自定义属性创建、更新和细分联系人
- **营销活动** - 以编程方式创建和发送邮件营销活动
- **事件跟踪** - 通过 Brevo Tracker 跟踪自定义事件和网站活动
- **电子商务同步** - 同步产品、订单和购物车数据，用于个性化营销活动
- **忠诚度计划** - 管理忠诚度订阅、积分和会员数据
- **Webhook 支持** - 交易、营销和 CRM 事件的实时通知
- **对话** - 实时聊天小部件集成和程序化消息管理

## 前提条件

开始之前，请确保您已具备：

1. Brevo 账户（免费、入门、商业或企业计划）
2. 从 Brevo 设置 > API 密钥生成的 API 密钥
3. 具有 API 访问权限的 Tajo 账户
4. 已验证的发件人域名（用于邮件发送）

## 认证

Brevo 支持两种认证方式：

### API 密钥认证（推荐）

在每次请求的 `api-key` 请求头中包含您的 API 密钥。最适合直接集成和服务器间通信。

```bash
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 集成不适合公开分发或市场上架。

## 配置

### 基础设置

```yaml
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 | 当前忠诚度计划积分余额 |

#### 自定义属性映射

```yaml
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_POINTS
```

## API 端点

### 核心端点

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `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` | 访问产品页面 | 浏览放弃跟踪 |

## 代码示例

### 初始化连接器

```javascript
import { TajoClient } from '@tajo/sdk';

const tajo = new TajoClient({
  apiKey: process.env.TAJO_API_KEY,
  brevoApiKey: process.env.BREVO_API_KEY
});

// Connect Brevo account
await tajo.connectors.connect('brevo', {
  apiKey: process.env.BREVO_API_KEY
});
```

### 发送交易邮件

```javascript
// Send a transactional email via Brevo
await tajo.brevo.sendTransactionalEmail({
  to: [{ email: 'customer@example.com', name: 'John Doe' }],
  templateId: 12,
  params: {
    ORDER_ID: '12345',
    ORDER_TOTAL: '$59.99',
    DELIVERY_DATE: '2024-02-15'
  }
});
```

### 同步联系人

```javascript
// Bulk import contacts to Brevo
await tajo.connectors.sync('brevo', {
  type: 'full',
  resources: ['contacts'],
  options: {
    listIds: [5, 6],
    updateExisting: true,
    emptyContactsAttributes: false
  }
});

// Check sync status
const status = await tajo.connectors.status('brevo');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsSynced: 25400,
//   campaignsSent: 142,
//   eventsTracked: 89320
// }
```

### 跟踪自定义事件

```javascript
// Track a custom event for a contact
await tajo.brevo.trackEvent({
  email: 'customer@example.com',
  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 可访问性和日志 |
| 短信未发送 | 电话号码格式无效 | 使用带国家代码的国际格式 |

### 调试模式

启用详细日志记录：

```yaml
connectors:
  brevo:
    debug: true
    log_level: verbose
    log_webhooks: true
```

### 测试连接

```bash
tajo connectors test brevo
# ✓ API connection successful
# ✓ Contacts API accessible
# ✓ Transactional email ready
# ✓ SMS sending configured
# ✓ Webhooks registered
```

## 最佳实践

1. **使用 API 密钥轮换** - 定期轮换 API 密钥以确保安全
2. **实施 Webhook 验证** - 使用用户名/密码认证验证 Webhook 签名
3. **批量导入联系人** - 对大型数据集使用批量导入，而非单个 API 调用
4. **监控速率限制** - 检查速率限制响应头，避免 429 错误
5. **使用事件跟踪** - 实施 Brevo Tracker，获取全面的客户行为数据
6. **设置适当的发件人认证** - 配置 SPF、DKIM 和 DMARC，以获得最佳投递率

## 安全

- **API 密钥认证** - 通过 `api-key` 请求头进行基于密钥的访问
- **OAuth 2.0** - 私人集成的基于令牌的委托访问
- **Webhook 验证** - 安全 Webhook 调用的用户名和密码认证
- **TLS 加密** - 所有 API 通信在传输中加密
- **IP 白名单** - 企业计划可选 IP 限制

## 相关资源

- [Brevo API 文档](https://developers.brevo.com/docs/getting-started)
- [Brevo 认证指南](https://developers.brevo.com/docs/authentication-schemes)
- [Brevo 速率限制](https://developers.brevo.com/docs/api-limits)
- [Shopify 连接器](https://tajo.io/zh-cn/docs/connectors/ecommerce/shopify)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)