---
title: "Mailchimp 커넥터"
description: "Tajo를 통해 Mailchimp의 오디언스, 캠페인, 자동화, 참여 데이터를 Brevo와 동기화하는 완전한 통합 가이드입니다."
url: https://tajo.io/kr/docs/connectors/marketing/mailchimp/
markdown: https://tajo.io/kr/docs/connectors/marketing/mailchimp.md
lang: ko-KR
robots: noindex
---

Tajo 사전 이용 신청

이름과 회사 이메일 주소를 입력하세요. Tajo 이용 신청을 확인할 수 있는 링크를 이메일로 보내드립니다.

# Mailchimp 커넥터

커넥터 상태: 개발 중 구축 중입니다. 아직 검증되지 않았습니다.

| 원본 필드 | 대상 필드 | 예시 값 |
| --- | --- | --- |
| `record.id` | `source_id` | `record_1042` |
| `record.updated_at` | `updated_at` | `2026-10-18T08:00:00Z` |
| `record.value` | `value` | `sample_value` |

Mailchimp 계정을 Tajo를 통해 Brevo에 연결하여 원활한 오디언스 마이그레이션, 캠페인 데이터 동기화, 두 플랫폼 간의 통합 마케팅 자동화를 실현하십시오.

## 개요

| 속성 | 값 |
| --- | --- |
| **플랫폼** | Mailchimp |
| **카테고리** | Marketing |
| **설정 복잡도** | 쉬움 |
| **공식 통합** | 아니오 |
| **동기화 데이터** | 연락처, 캠페인, 자동화, 이벤트 |
| **API Base URL** | `https://{dc}.api.mailchimp.com/3.0` |

## 기능

- **오디언스 동기화** - Mailchimp 오디언스를 Brevo 연락처 목록과 마이그레이션 및 동기화
- **캠페인 데이터** - 통합 보고를 위한 캠페인 성능 데이터 동기화
- **자동화 마이그레이션** - Mailchimp 자동화를 Brevo 워크플로에 매핑
- **참여 지표** - 오픈, 클릭, 반송 데이터를 Brevo 속성에 동기화
- **세그먼트 매핑** - Mailchimp 세그먼트를 Brevo 목록 또는 세그먼트로 복제
- **이커머스 데이터** - Mailchimp 이커머스에서 스토어, 제품, 주문 데이터 동기화
- **태그 동기화** - Mailchimp 태그를 Brevo 연락처 속성 또는 목록에 매핑
- **템플릿 마이그레이션** - Brevo 캠페인에서 사용할 Mailchimp 템플릿 내보내기

## 사전 요구 사항

시작하기 전에 다음이 준비되어 있는지 확인하십시오.

1. Mailchimp 계정 (Free, Essentials, Standard 또는 Premium)
2. Mailchimp API 키 또는 OAuth 앱
3. API 접근이 가능한 Brevo 계정
4. Tajo 계정

## 인증

### API 키 인증

Mailchimp Account > Extras > API Keys에서 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
# 인증 URL
https://login.mailchimp.com/oauth2/authorize?
  response_type=code&
  client_id={client_id}&
  redirect_uri={redirect_uri}

# 토큰 교환
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"

    # 데이터 동기화 옵션
    sync:
      audiences: true
      campaigns: true
      automations: true
      ecommerce: true

    # 오디언스를 Brevo 목록에 매핑
    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 | 구독 상태 (subscribed, unsubscribed, cleaned, pending) |
| `tags` optional | array | 세그먼테이션을 위한 구독자 태그 |
| `stats.avg_open_rate` optional | number | 평균 이메일 오픈율 |
| `stats.avg_click_rate` optional | number | 평균 이메일 클릭률 |

#### 맞춤 병합 필드 매핑

```yaml
field_mapping:
  # 표준 필드
  email_address: email
  FNAME: FIRSTNAME
  LNAME: LASTNAME
  PHONE: SMS

  # 참여 지표
  stats.avg_open_rate: AVG_OPEN_RATE
  stats.avg_click_rate: AVG_CLICK_RATE
  member_rating: ENGAGEMENT_SCORE

  # 이커머스 필드
  ecommerce_data.total_revenue: TOTAL_REVENUE
  ecommerce_data.number_of_orders: ORDER_COUNT

  # 맞춤 병합 필드
  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
});

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

### 오디언스를 Brevo로 마이그레이션

```javascript
// Mailchimp에서 Brevo로의 전체 오디언스 마이그레이션
await tajo.connectors.sync('mailchimp', {
  type: 'full',
  resources: ['audiences', 'campaigns', 'ecommerce'],
  options: {
    preserveTags: true,
    migrateSegments: true,
    includeUnsubscribed: false
  }
});

// 마이그레이션 상태 확인
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
// 캠페인 성능을 Brevo 속성에 동기화
await tajo.connectors.sync('mailchimp', {
  type: 'incremental',
  resources: ['campaigns'],
  options: {
    syncEngagement: true,
    updateContactMetrics: true,
    since: '2024-01-01'
  }
});
```

## 속도 제한

Mailchimp Marketing API 속도 제한:

| 유형 | 제한 | 세부 사항 |
| --- | --- | --- |
| 표준 | 10개 동시 요청 | API 키당 |
| 배치 작업 | 배치당 500개 작업 | 요청당 |
| 내보내기 제한 | 1개 동시 내보내기 | 계정당 |
| 트랜잭션 | 25 요청/초 | API 키당 |

속도 제한 전략

Mailchimp는 초당 요청보다는 동시 연결을 제한합니다. 배치 엔드포인트를 사용하고 `429` 응답에 대해 지수 백오프로 재시도 로직을 구현하십시오.

## 문제 해결

### 일반적인 문제

| 문제 | 원인 | 해결 방법 |
| --- | --- | --- |
| 401 Unauthorized | 잘못된 API 키 또는 데이터 센터 | API 키 확인 및 올바른 `dc` 접두사 추출 |
| 멤버가 이미 존재함 | 이메일이 이미 오디언스에 있음 | 기존 멤버 업데이트에 POST 대신 PUT 사용 |
| 규정 준수 상태 | GDPR 삭제로 재추가 방지 | 연락처는 가입 폼을 통해 재구독해야 함 |
| 배치 시간 초과 | 대규모 배치 작업 | 500개 작업의 더 작은 배치로 분할 |
| 병합 필드 누락 | 맞춤 필드가 생성되지 않음 | 매핑 전에 Mailchimp에서 병합 필드 생성 |

### 디버그 모드

자세한 로깅 활성화:

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

### 연결 테스트

```bash
tajo connectors test mailchimp
# ✓ API 연결 성공
# ✓ 오디언스 읽기 가능
# ✓ 캠페인 읽기 가능
# ✓ 이커머스 데이터 접근 가능
# ✓ 웹훅 구성됨
```

## 모범 사례

1. **배치 작업 사용** - 대량 업데이트에 배치 구독/구독 취소 사용
2. **구독자 상태 보존** - 마이그레이션 중 구독 동의 존중
3. **먼저 병합 필드 매핑** - 동기화 전에 해당하는 Brevo 속성 생성
4. **참여 데이터 동기화** - 과거 세그먼테이션을 위한 오픈/클릭률 가져오기
5. **규정 준수 상태 처리** - GDPR 및 영구 삭제 상태 준수
6. **증분 동기화 사용** - API 사용을 줄이기 위해 마지막 동기화 이후 변경 사항만 동기화

## 보안

- **API 키 인증** - HTTP Basic Auth 비밀번호로 전달되는 시크릿 키
- **OAuth 2.0** - 다중 계정 접근을 위한 토큰 기반 인증
- **TLS 암호화** - HTTPS를 통해 암호화된 모든 API 통신
- **웹훅 확인** - 공유 시크릿으로 웹훅 소스 검증
- **데이터 센터 격리** - 지역별 데이터 센터에 저장된 데이터

## 관련 리소스

- [Mailchimp Marketing API 레퍼런스](https://mailchimp.com/developer/marketing/api/)
- [Mailchimp API 가이드](https://mailchimp.com/developer/marketing/guides/quick-start/)
- [Brevo 커넥터](https://tajo.io/kr/docs/connectors/marketing/brevo)
- [ActiveCampaign 커넥터](https://tajo.io/kr/docs/connectors/marketing/activecampaign)
- [고객 동기화 스킬](https://tajo.io/kr/docs/skills/data-sync/customer-sync)