---
title: "Mailchimp 连接器"
description: "完整的 Mailchimp 集成指南，通过 Tajo 将受众群体、营销活动、自动化和参与数据与 Brevo 同步。"
url: https://tajo.io/zh-cn/docs/connectors/marketing/mailchimp/
markdown: https://tajo.io/zh-cn/docs/connectors/marketing/mailchimp.md
lang: zh-CN
robots: noindex
---

申请抢先体验

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

# Mailchimp 连接器

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

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

通过 Tajo 将您的 Mailchimp 账户连接到 Brevo，实现无缝的受众群体迁移、营销活动数据同步以及两个平台之间统一的营销自动化。

## 概览

| 属性 | 值 |
| --- | --- |
| **平台** | Mailchimp |
| **类别** | 营销 |
| **设置复杂度** | 简单 |
| **官方集成** | 否 |
| **同步数据** | 联系人、营销活动、自动化、事件 |
| **API 基础 URL** | `https://{dc}.api.mailchimp.com/3.0` |

## 功能

- **受众群体同步** - 迁移并同步 Mailchimp 受众群体与 Brevo 联系人列表
- **营销活动数据** - 同步营销活动绩效数据，用于统一报告
- **自动化迁移** - 将 Mailchimp 自动化映射到 Brevo 工作流
- **参与指标** - 将打开次数、点击次数和退回数据同步到 Brevo 属性
- **细分映射** - 将 Mailchimp 细分复制为 Brevo 列表或细分
- **电子商务数据** - 同步 Mailchimp 电子商务中的商店、产品和订单数据
- **标签同步** - 将 Mailchimp 标签映射到 Brevo 联系人属性或列表
- **模板迁移** - 导出 Mailchimp 模板用于 Brevo 营销活动

## 前提条件

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

1. Mailchimp 账户（免费、Essentials、Standard 或 Premium 版本）
2. Mailchimp API 密钥或 OAuth 应用
3. 具有 API 访问权限的 Brevo 账户
4. Tajo 账户

## 认证

### API 密钥认证

从 Mailchimp 账户 > 附加功能 > API 密钥生成 API 密钥。

```bash
curl https://{dc}.api.mailchimp.com/3.0/ping \
  --user "anystring:{api_key}" \
  -H "Content-Type: application/json"
```

`{dc}` 数据中心前缀是 API 密钥的最后一部分（例如 `us21`）。

### OAuth 2.0

用于多账户集成：

```bash
# Authorization URL
https://login.mailchimp.com/oauth2/authorize?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}

# Token exchange
curl -X POST https://login.mailchimp.com/oauth2/token \
  -d "grant_type=authorization_code" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "redirect_uri={redirect_uri}" \
  -d "code={auth_code}"
```

数据中心

始终从您的 API 密钥或 OAuth 元数据端点提取数据中心。使用错误的数据中心将导致认证失败。

## 配置

### 基础设置

```yaml
connectors:
  mailchimp:
    enabled: true
    api_key: "${MAILCHIMP_API_KEY}"
    data_center: "us21"

    # Data sync options
    sync:
      audiences: true
      campaigns: true
      automations: true
      ecommerce: true

    # Audience to Brevo list mapping
    audience_mapping:
      "Main Audience": 40
      "Newsletter": 41
      "Customers": 42
```

### 字段映射

将 Mailchimp 合并字段映射到 Brevo 联系人属性：

#### 默认映射

| Parameter | Type | Description |
| --- | --- | --- |
| `email_address` required | string | 订阅者邮箱（唯一标识符） |
| `FNAME` optional | string | 名字合并字段，映射到 FIRSTNAME |
| `LNAME` optional | string | 姓氏合并字段，映射到 LASTNAME |
| `PHONE` optional | string | 电话合并字段，映射到 SMS |
| `status` optional | string | 订阅状态（已订阅、已退订、已清理、待确认） |
| `tags` optional | array | 用于细分的订阅者标签 |
| `stats.avg_open_rate` optional | number | 平均邮件打开率 |
| `stats.avg_click_rate` optional | number | 平均邮件点击率 |

#### 自定义合并字段映射

```yaml
field_mapping:
  # Standard fields
  email_address: email
  FNAME: FIRSTNAME
  LNAME: LASTNAME
  PHONE: SMS

  # Engagement metrics
  stats.avg_open_rate: AVG_OPEN_RATE
  stats.avg_click_rate: AVG_CLICK_RATE
  member_rating: ENGAGEMENT_SCORE

  # E-commerce fields
  ecommerce_data.total_revenue: TOTAL_REVENUE
  ecommerce_data.number_of_orders: ORDER_COUNT

  # Custom merge fields
  MMERGE5: COMPANY_NAME
  MMERGE6: CUSTOMER_TYPE
```

## API 端点

### 受众群体（列表）

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/3.0/lists` | 列出所有受众群体 |
| `GET` | `/3.0/lists/{list_id}` | 获取受众群体详情 |
| `GET` | `/3.0/lists/{list_id}/members` | 列出受众群体成员 |
| `POST` | `/3.0/lists/{list_id}/members` | 添加成员 |
| `PUT` | `/3.0/lists/{list_id}/members/{hash}` | 更新成员 |
| `POST` | `/3.0/lists/{list_id}` | 批量订阅/退订 |

### 营销活动

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/3.0/campaigns` | 列出营销活动 |
| `GET` | `/3.0/campaigns/{id}` | 获取营销活动详情 |
| `GET` | `/3.0/reports/{id}` | 获取营销活动报告 |
| `GET` | `/3.0/reports/{id}/email-activity` | 获取邮件活动 |

### 自动化

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/3.0/automations` | 列出自动化 |
| `GET` | `/3.0/automations/{id}` | 获取自动化详情 |
| `GET` | `/3.0/automations/{id}/emails` | 列出自动化邮件 |

### 电子商务

| 方法 | 端点 | 描述 |
| --- | --- | --- |
| `GET` | `/3.0/ecommerce/stores` | 列出已连接的商店 |
| `GET` | `/3.0/ecommerce/stores/{id}/customers` | 列出商店客户 |
| `GET` | `/3.0/ecommerce/stores/{id}/orders` | 列出商店订单 |
| `GET` | `/3.0/ecommerce/stores/{id}/products` | 列出商店产品 |

## 事件

### 营销活动事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `campaign.sent` | 营销活动已送达 | 绩效跟踪 |
| `campaign.opened` | 邮件已打开 | 参与度评分 |
| `campaign.clicked` | 链接已点击 | 兴趣跟踪 |
| `campaign.bounced` | 邮件退回 | 列表清洗 |

### 订阅者事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `subscribe` | 新订阅者加入 | 欢迎流程 |
| `unsubscribe` | 订阅者退出 | 偏好管理 |
| `profile` | 档案更新 | 属性同步 |
| `cleaned` | 邮件已清理（退回） | 列表维护 |

### 电子商务事件

| 事件 | 触发条件 | 使用场景 |
| --- | --- | --- |
| `ecommerce.order` | 订单已下单 | 购买后流程 |
| `ecommerce.cart` | 购物车已更新 | 放弃购物车召回 |

## 代码示例

### 初始化连接器

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

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

// Connect Mailchimp
await tajo.connectors.connect('mailchimp', {
  apiKey: process.env.MAILCHIMP_API_KEY
});
```

### 将受众群体迁移到 Brevo

```javascript
// Full audience migration from Mailchimp to Brevo
await tajo.connectors.sync('mailchimp', {
  type: 'full',
  resources: ['audiences', 'campaigns', 'ecommerce'],
  options: {
    preserveTags: true,
    migrateSegments: true,
    includeUnsubscribed: false
  }
});

// Check migration status
const status = await tajo.connectors.status('mailchimp');
console.log(status);
// {
//   connected: true,
//   lastSync: '2024-01-15T10:30:00Z',
//   contactsMigrated: 52000,
//   campaignsSynced: 245,
//   segmentsMapped: 18
// }
```

### 同步营销活动参与数据

```javascript
// Sync campaign performance to Brevo attributes
await tajo.connectors.sync('mailchimp', {
  type: 'incremental',
  resources: ['campaigns'],
  options: {
    syncEngagement: true,
    updateContactMetrics: true,
    since: '2024-01-01'
  }
});
```

## 速率限制

Mailchimp 营销 API 速率限制：

| 类型 | 限制 | 详情 |
| --- | --- | --- |
| 标准 | 10 个并发请求 | 每个 API 密钥 |
| 批量操作 | 每批次 500 个操作 | 每次请求 |
| 导出限制 | 1 个并发导出 | 每账户 |
| 交易 | 25 请求/秒 | 每个 API 密钥 |

速率限制策略

Mailchimp 限制并发连接数，而非每秒请求数。使用批量端点，并在 `429` 响应时实施带指数退避的重试逻辑。

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
| --- | --- | --- |
| 401 Unauthorized | API 密钥无效或数据中心错误 | 验证 API 密钥并提取正确的 `dc` 前缀 |
| 成员已存在 | 邮箱已在受众群体中 | 使用 PUT 代替 POST 更新现有成员 |
| 合规状态 | GDPR 删除阻止重新添加 | 联系人必须通过注册表单重新订阅 |
| 批量超时 | 大型批量操作 | 拆分为每批 500 个操作的较小批次 |
| 缺少合并字段 | 自定义字段未创建 | 在映射前在 Mailchimp 中创建合并字段 |

### 调试模式

启用详细日志记录：

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

### 测试连接

```bash
tajo connectors test mailchimp
# ✓ API connection successful
# ✓ Audiences readable
# ✓ Campaigns readable
# ✓ E-commerce data accessible
# ✓ Webhook configured
```

## 最佳实践

1. **使用批量操作** - 使用批量订阅/退订进行批量更新
2. **保留订阅者状态** - 迁移期间尊重订阅同意
3. **先映射合并字段** - 同步前创建相应的 Brevo 属性
4. **同步参与数据** - 导入打开/点击率用于历史细分
5. **处理合规状态** - 尊重 GDPR 和永久删除状态
6. **使用增量同步** - 仅同步自上次同步以来的变更，减少 API 使用量

## 安全

- **API 密钥认证** - 通过 HTTP 基本认证密码传递的密钥
- **OAuth 2.0** - 用于多账户访问的基于令牌的授权
- **TLS 加密** - 所有 API 通信通过 HTTPS 加密
- **Webhook 验证** - 使用共享密钥验证 Webhook 来源
- **数据中心隔离** - 数据存储在特定区域的数据中心

## 相关资源

- [Mailchimp 营销 API 参考](https://mailchimp.com/developer/marketing/api/)
- [Mailchimp API 指南](https://mailchimp.com/developer/marketing/guides/quick-start/)
- [Brevo 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/brevo)
- [ActiveCampaign 连接器](https://tajo.io/zh-cn/docs/connectors/marketing/activecampaign)
- [客户同步技能](https://tajo.io/zh-cn/docs/skills/data-sync/customer-sync)