---
title: "Iterable 连接器"
description: "完整的 Iterable 集成指南，通过 Tajo 将用户、营销活动、实验和参与事件与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/iterable/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/iterable.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# Iterable 连接器

连接器状态: 计划中 尚未构建。Tajo 目前不运行此连接器。

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

将您的 Iterable 增长营销平台连接到 Brevo，实现统一的客户参与、跨渠道营销活动协调以及跨营销工具的综合分析。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Iterable |
| **类别** | 营销 |
| **设置复杂度** | 中等 |
| **官方集成** | 否 |
| **同步数据** | 用户、事件、营销活动、目录 |
| **API 类型** | REST API |
| **认证方式** | API 密钥 |
| **基础 URL** | `https://api.iterable.com/api/` |

## 功能

- **用户档案同步** - 与 Brevo 联系人的双向用户数据同步
- **营销活动分析** - 同步营销活动发送、打开和点击指标，用于统一报告
- **实验数据** - 跟踪 A/B 测试结果和获胜变体
- **目录同步** - 跨平台同步产品和内容目录
- **工作流事件** - 将工作流触发和完成事件转发到 Brevo
- **渠道偏好同步** - 在 Brevo 中复制用户通信偏好

## 前提条件

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

1. 具有 API 访问权限的 Iterable 账户
2. 具有适当权限的 Iterable API 密钥
3. 您的 Iterable 项目 ID
4. 具有 API 访问权限的 Brevo 账户
5. 具有有效订阅的 Tajo 账户

## 认证

Iterable 使用在请求头中传递的 API 密钥认证。

### 创建 API 密钥

1. 登录您的 Iterable 仪表板
2. 导航到**集成** > **API 密钥**
3. 点击**新建 API 密钥**
4. 命名为”Tajo Integration”
5. 选择**服务器端**密钥类型
6. 授予以下权限：

```
Users: Read/Write
Events: Read/Write
Campaigns: Read
Lists: Read/Write
Catalogs: Read
Experiments: Read
Workflows: Read
Templates: Read
Channels: Read
Message Types: Read
```

密钥类型很重要

Tajo 集成请始终使用**服务器端** API 密钥。移动端和 JavaScript 端密钥权限受限，无法访问所有必需端点。

### 连接到 Tajo

```bash
tajo connectors install iterable \
  --api-key $ITERABLE_API_KEY
```

## 配置

### 基础设置

```yaml
connectors:
  iterable:
    enabled: true

    sync:
      users: true
      events: true
      campaigns: true
      catalogs: true
      experiments: true

    lists:
      all_users: 16
      engaged_users: 17
      inactive_users: 18
```

### 字段映射

将 Iterable 用户字段映射到 Brevo 联系人属性：

```yaml
field_mapping:
  # Standard fields
  userId: ITERABLE_ID
  email: email
  firstName: FIRSTNAME
  lastName: LASTNAME
  phoneNumber: SMS

  # Engagement data
  signupDate: SIGNUP_DATE
  totalPurchases: TOTAL_PURCHASES
  lastPurchaseDate: LAST_PURCHASE

  # Custom fields
  plan_name: PLAN_NAME
  company_size: COMPANY_SIZE
  preferred_channel: PREFERRED_CHANNEL
  lifecycle_stage: LIFECYCLE_STAGE
```

### 事件配置

```yaml
event_mapping:
  # Iterable event -> Brevo event
  purchase: ORDER_PLACED
  addToCart: CART_UPDATED
  pageView: PAGE_VIEWED
  appOpen: APP_OPENED
  pushOpen: PUSH_ENGAGED
```

## API 端点

Tajo 集成以下 Iterable API 端点：

| 端点 | 方法 | 用途 |
| --- | --- | --- |
| `/users/update` | POST | 更新用户档案 |
| `/users/{email}` | GET | 通过邮箱检索用户 |
| `/users/bulkUpdate` | POST | 批量更新用户 |
| `/events/track` | POST | 跟踪自定义事件 |
| `/events/trackBulk` | POST | 批量跟踪事件 |
| `/campaigns` | GET | 列出所有营销活动 |
| `/campaigns/metrics` | GET | 营销活动绩效数据 |
| `/experiments/metrics` | GET | 实验结果 |
| `/lists` | GET | 列出所有用户列表 |
| `/lists/subscribe` | POST | 将用户添加到列表 |
| `/lists/unsubscribe` | POST | 从列表中移除用户 |
| `/catalogs/{catalogName}/items` | GET | 检索目录项目 |
| `/channels` | GET | 列出消息渠道 |
| `/export/data.json` | GET | 导出原始事件数据 |

## 代码示例

### 初始化连接器

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

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

await tajo.connectors.connect('iterable', {
  apiKey: process.env.ITERABLE_API_KEY
});
```

### 同步用户

```javascript
// Incremental user sync from Iterable to Brevo
await tajo.connectors.sync('iterable', {
  type: 'incremental',
  resources: ['users'],
  since: '2024-01-01',
  batchSize: 50
});

const status = await tajo.connectors.status('iterable');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-03-15T09:45:00Z',
//   usersCount: 58700,
//   campaignsTracked: 42,
//   eventsProcessed: 210000
// }
```

### 跟踪事件

```javascript
// Forward Iterable events to Brevo
await tajo.connectors.handleEvent('iterable', {
  type: 'custom_event',
  payload: {
    email: 'user@example.com',
    eventName: 'subscription_upgraded',
    dataFields: {
      previousPlan: 'starter',
      newPlan: 'pro',
      mrr: 99.00
    }
  }
});
```

### Webhook 处理器

```javascript
// Handle Iterable system webhooks
app.post('/webhooks/iterable', async (req, res) => {
  const event = req.body;

  await tajo.connectors.handleWebhook('iterable', {
    type: event.eventName,
    payload: event
  });

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

## 速率限制

Iterable 根据您的计划实施速率限制：

| 计划 | 速率限制 | 批量端点限制 |
| --- | --- | --- |
| **Growth** | 500 请求/秒 | 500 请求/秒 |
| **Enterprise** | 自定义 | 自定义 |

特定端点限制：

| 端点 | 限制 |
| --- | --- |
| `/users/update` | 500 请求/秒 |
| `/users/bulkUpdate` | 500 请求/秒（每次请求 1,000 个用户） |
| `/events/track` | 500 请求/秒 |
| `/events/trackBulk` | 500 请求/秒（每次请求 8,000 个事件） |
| `/export/data.json` | 4 个并发请求 |

批量端点

Tajo 自动批量处理用户更新（每次调用最多 1,000 个）和事件跟踪（每次调用最多 8,000 个），在速率限制内最大化吞吐量。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | API 密钥无效 | 在 Iterable > 集成 > API 密钥中验证密钥 |
| 用户未同步 | 密钥类型不匹配 | 确保使用服务器端 API 密钥 |
| 营销活动数据缺失 | 权限不足 | 向 API 密钥添加营销活动读取权限 |
| 导出超时 | 数据量过大 | 使用日期范围筛选器减少导出大小 |
| 重复用户 | 标识符不一致 | 始终使用邮箱作为主要标识符 |

### 调试模式

```yaml
connectors:
  iterable:
    debug: true
    log_level: verbose
    log_api_calls: true
```

### 测试连接

```bash
tajo connectors test iterable
# ✓ API connection successful
# ✓ User data accessible
# ✓ Campaign list readable
# ✓ Event tracking operational
# ✓ List management available
```

## 最佳实践

1. **使用批量端点** - 对大数据量始终优先使用 `bulkUpdate` 和 `trackBulk`
2. **按邮箱去重** - 使用邮箱作为 Iterable 和 Brevo 之间一致的标识符
3. **增量同步** - 使用日期范围避免重新处理历史数据
4. **映射渠道偏好** - 同步选择加入/退出状态以维持合规
5. **监控导出任务** - 大型导出可能需要时间；设置状态轮询
6. **用非生产项目测试** - 在同步生产数据前验证映射

## 安全

- **API 密钥认证** - 具有细粒度权限的服务器端密钥
- **仅 HTTPS** - 所有 API 通信通过 TLS 1.2+ 加密
- **密钥轮换** - 支持轮换期间多个有效 API 密钥
- **加密存储** - API 凭据在 Tajo 中静态加密
- **JWT Webhook** - Webhook 负载使用 JWT 签名进行验证

## 相关资源

- [Braze 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/braze)
- [Customer.io 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/customerio)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)
- [Brevo 联系人 API](https://tajo.io/zh-cn/docs/contact-management)