---
title: "SendGrid 连接器"
description: "完整的 SendGrid 集成指南，通过 Tajo 将联系人、交易邮件、营销活动和参与事件与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/sendgrid/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/sendgrid.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# SendGrid 连接器

连接器状态: 开发中 正在构建，尚未验证。

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

通过 Tajo 将您的 SendGrid 账户连接到 Brevo，实现邮件基础设施迁移、联系人同步、营销活动数据传输以及两个平台上的统一参与分析。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | SendGrid（Twilio） |
| **类别** | 营销 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 联系人、营销活动、交易邮件、事件 |
| **API 基础 URL** | `https://api.sendgrid.com/v3` |

## 功能

- **联系人迁移** - 将 SendGrid 营销联系人迁移到 Brevo（含自定义字段）
- **交易邮件同步** - 跟踪交易邮件事件，用于统一报告
- **营销活动数据** - 同步 Single Send 和自动化营销活动绩效数据
- **事件 Webhook** - 将邮件事件（已投递、已打开、已点击、退回）转发到 Brevo
- **抑制同步** - 迁移退回、封锁和退订列表以确保合规
- **模板迁移** - 导出动态交易模板供 Brevo 使用
- **发件人验证** - 同步已验证的发件人身份和域名认证
- **统计同步** - 将历史参与统计数据导入 Brevo 属性

## 前提条件

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

1. SendGrid 账户（免费、Essentials、Pro 或 Premier 版本）
2. 具有所需权限的 SendGrid API 密钥
3. 具有 API 访问权限的 Brevo 账户
4. Tajo 账户

## 认证

### API 密钥认证

SendGrid 使用 Bearer 令牌认证。

```bash
curl https://api.sendgrid.com/v3/marketing/contacts \
  -H "Authorization: Bearer SG.YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

在 SendGrid 设置 > API 密钥中创建 API 密钥，具体权限级别：

- **完全访问** - 完整 API 访问
- **受限访问** - 细粒度权限控制
- **账单访问** - 仅限账单操作

#### 所需权限

```
Marketing: Full Access
  - Contacts (read)
  - Single Sends (read)
  - Automations (read)
Mail Send: Full Access
  - Mail Send (read)
Stats: Read Access
Suppressions: Read Access
Tracking: Read Access
```

API 密钥安全

SendGrid API 密钥仅在创建时显示一次。请安全存储。如果丢失，必须创建新密钥。

## 配置

### 基础设置

```yaml
connectors:
  sendgrid:
    enabled: true
    api_key: "${SENDGRID_API_KEY}"

    # Data sync options
    sync:
      contacts: true
      campaigns: true
      transactional: true
      suppressions: true
      statistics: true

    # List mapping to Brevo
    list_mapping:
      "All Contacts": 60
      "Newsletter": 61
      "Transactional": 62
```

### 字段映射

将 SendGrid 联系人字段映射到 Brevo 联系人属性：

#### 默认映射

| Parameter | Type | Description |
| --- | --- | --- |
| `email` required | string | 联系人邮箱地址（唯一标识符） |
| `first_name` optional | string | 映射到 FIRSTNAME 属性 |
| `last_name` optional | string | 映射到 LASTNAME 属性 |
| `phone_number` optional | string | 映射到 SMS 属性 |
| `city` optional | string | 联系人城市 |
| `country` optional | string | 联系人国家 |
| `custom_fields` optional | object | 自定义字段键值对 |
| `list_ids` optional | array | SendGrid 列表会员资格 |

#### 自定义字段映射

```yaml
field_mapping:
  # Standard fields
  email: email
  first_name: FIRSTNAME
  last_name: LASTNAME
  phone_number: SMS

  # Location fields
  city: CITY
  state_province_region: STATE
  country: COUNTRY
  postal_code: POSTAL_CODE

  # Engagement metrics
  avg_open_rate: AVG_OPEN_RATE
  avg_click_rate: AVG_CLICK_RATE

  # Custom fields
  custom_fields.company: COMPANY_NAME
  custom_fields.plan: PLAN_TYPE
```

## API 端点

### 营销联系人

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `PUT` | `/v3/marketing/contacts` | 添加或更新联系人 |
| `POST` | `/v3/marketing/contacts/search` | 搜索联系人 |
| `GET` | `/v3/marketing/contacts/count` | 获取联系人数量 |
| `POST` | `/v3/marketing/contacts/exports` | 导出联系人 |
| `DELETE` | `/v3/marketing/contacts` | 删除联系人 |
| `GET` | `/v3/marketing/lists` | 列出所有联系人列表 |

### 交易邮件（邮件发送）

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `POST` | `/v3/mail/send` | 发送邮件 |
| `GET` | `/v3/templates` | 列出动态模板 |
| `GET` | `/v3/templates/{id}` | 获取模板详情 |

### 营销活动（Single Sends）

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/v3/marketing/singlesends` | 列出 Single Sends |
| `GET` | `/v3/marketing/singlesends/{id}` | 获取 Single Send 详情 |
| `GET` | `/v3/marketing/automations` | 列出自动化 |

### 统计数据

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/v3/stats` | 获取全局邮件统计数据 |
| `GET` | `/v3/categories/stats` | 获取类别统计数据 |
| `GET` | `/v3/marketing/stats/singlesends` | 获取 Single Send 统计数据 |

### 抑制

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/v3/suppression/bounces` | 列出退回邮件 |
| `GET` | `/v3/suppression/blocks` | 列出封锁邮件 |
| `GET` | `/v3/suppression/spam_reports` | 列出垃圾邮件报告 |
| `GET` | `/v3/suppression/unsubscribes` | 列出全局退订 |

## 事件

### 邮件事件（通过事件 Webhook）

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `processed` | SendGrid 接受邮件 | 发送确认 |
| `delivered` | 邮件已投递给收件人 | 投递跟踪 |
| `open` | 邮件已打开 | 参与度评分 |
| `click` | 链接已点击 | 兴趣跟踪 |
| `bounce` | 邮件退回 | 列表清洗 |
| `dropped` | 邮件被抑制 | 合规审查 |
| `deferred` | 投递延迟 | 重试监控 |
| `spam_report` | 标记为垃圾邮件 | 声誉管理 |
| `unsubscribe` | 通过链接退订 | 偏好同步 |

## 代码示例

### 初始化连接器

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

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

// Connect SendGrid
await tajo.connectors.connect('sendgrid', {
  apiKey: process.env.SENDGRID_API_KEY
});
```

### 将联系人迁移到 Brevo

```javascript
// Full contact migration from SendGrid to Brevo
await tajo.connectors.sync('sendgrid', {
  type: 'full',
  resources: ['contacts', 'suppressions'],
  options: {
    includeCustomFields: true,
    migrateListMemberships: true,
    migrateSuppressions: true
  }
});

// Check migration status
const status = await tajo.connectors.status('sendgrid');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 45000,
//   suppressionsSynced: 3200,
//   listsMapped: 8
// }
```

### 转发邮件事件

```javascript
// Handle SendGrid Event Webhook
app.post('/webhooks/sendgrid', async (req, res) => {
  const signature = req.get('X-Twilio-Email-Event-Webhook-Signature');

  // Verify webhook signature (ECDSA)
  if (!verifySendGridSignature(req.body, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // Process batch of events
  for (const event of req.body) {
    await tajo.connectors.handleWebhook('sendgrid', {
      type: event.event,
      email: event.email,
      timestamp: event.timestamp,
      payload: event
    });
  }

  res.status(200).send('OK');
});
```

## 速率限制

SendGrid API 速率限制：

| 端点 | 限制 | 详情 |
| --- | --- | --- |
| 邮件发送 (`/v3/mail/send`) | 根据计划而定 | 免费版：100/天，Essentials 版根据计划 |
| 营销联系人 PUT | 3 请求/秒 | 每批最多 30,000 个联系人 |
| 营销联系人搜索 | 50 请求/秒 | 每个 API 密钥 |
| 通用 API | 1,000 请求/秒 | 每个 API 密钥 |
| 事件 Webhook | 批量投递 | 每次 POST 最多 1,000 个事件 |

邮件发送限制

邮件发送限制取决于您的 SendGrid 计划。免费账户每天限制 100 封邮件。请查看您的计划详情以了解确切的发送限制。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | API 密钥无效 | 在 SendGrid 设置中验证 API 密钥 |
| 403 Forbidden | API 密钥权限不足 | 使用所需范围创建新密钥 |
| 联系人导出待处理 | 大型数据集处理中 | 轮询导出状态端点直至完成 |
| 抑制同步不完整 | 需要分页 | 使用偏移量参数实现分页 |
| 未收到事件 Webhook | URL 未验证 | 在 SendGrid 中完成 Webhook URL 验证 |

### 调试模式

启用详细日志记录：

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

### 测试连接

```bash
tajo connectors test sendgrid
# ✓ API connection successful
# ✓ Contacts readable
# ✓ Lists accessible
# ✓ Statistics readable
# ✓ Suppressions accessible
```

## 最佳实践

1. **先迁移抑制记录** - 发送前确保退回、封锁和退订记录已在 Brevo 中
2. **使用批量联系人上传** - 每次请求最多 PUT 30,000 个联系人以提高效率
3. **验证事件 Webhook** - 使用 ECDSA 验证启用签名 Webhook
4. **映射自定义字段** - 联系人迁移前在 Brevo 中创建相应属性
5. **同步参与数据** - 导入历史统计数据，用于 Brevo 中的细分
6. **处理异步导出** - 联系人导出是异步的；轮询以确认完成

## 安全

- **API 密钥认证** - 具有细粒度权限级别的 Bearer 令牌
- **事件 Webhook 签名** - ECDSA 签名验证 Webhook 负载
- **TLS 加密** - 所有 API 通信通过 HTTPS 加密
- **IP 访问管理** - 按 IP 限制仪表板和 API 访问
- **双因素认证** - 账户访问可使用双因素认证

## 相关资源

- [SendGrid API 文档](https://docs.sendgrid.com/api-reference)
- [SendGrid 事件 Webhook 指南](https://docs.sendgrid.com/for-developers/tracking-events/event)
- [Brevo 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/brevo)
- [Mailchimp 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/mailchimp)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)