Mailchimp API 리스트
Mailchimp API 리스트
Mailchimp의 리스트(list)는 '오디언스(audience)'라고도 불러요. 모든 연락처(contact)를 저장하고 관리하는 곳이 바로 리스트예요. Mailchimp 마케팅 API를 쓰면 이 리스트를 만들고, 연락처를 추가하고, 세그먼트로 나누고, 가입 폼과 웹훅까지 한 곳에서 관리할 수 있어요. 이 문서에서는 리스트/오디언스 관련 API의 핵심 기능과 사용 방법을 정리해 볼게요.
출처: 문서
본문
리스트(list) 관리
리스트는 계정 안의 모든 구독자를 담는 그릇이에요. 다음 API로 리스트를 만들고 조회하고 수정하고 삭제해요.
GET /lists # 계정의 모든 리스트 정보 조회
POST /lists # 새 리스트 생성
GET /lists/{list_id} # 특정 리스트 정보 조회
PATCH /lists/{list_id} # 특정 리스트 설정 수정
DELETE /lists/{list_id} # 리스트 삭제
POST /lists/{list_id} # 리스트 멤버 일괄 구독/해지
리스트를 삭제하면 구독 활동, 해지, 컴플레인, 반송(bounce) 같은 리스트 히스토리를 전부 잃어요. 구독자의 이메일 주소도 미리 내보내기(export)와 백업을 해두지 않으면 사라지므로 주의해야 해요. 리스트 정보를 조회하면 아직 구독 확인(confirm)을 하지 않은 가입자, 해지했거나 정리(cleaned)된 멤버 결과도 함께 확인할 수 있어요.
멤버(member) 가입·조회·수정
구독자를 리스트에 추가하거나 정보를 읽고 고치는 건 멤버 엔드포인트에서 처리해요. 현재 구독 중, 해지됨, 반송(bounce)된 멤버를 모두 다뤄요.
GET /lists/{list_id}/members # 리스트 멤버 목록 조회
POST /lists/{list_id}/members # 새 멤버를 리스트에 추가
GET /lists/{list_id}/members/{subscriber_hash} # 특정 멤버 정보 조회
PUT /lists/{list_id}/members/{subscriber_hash} # 멤버 추가 또는 갱신(upsert)
PATCH /lists/{list_id}/members/{subscriber_hash} # 특정 멤버 정보 수정
DELETE /lists/{list_id}/members/{subscriber_hash} # 멤버 보관(archive)
POST /lists/{list_id}/members/{subscriber_hash}/actions/delete-permanent # 멤버 영구 삭제
subscriber_hash는 구독자의 이메일 주소를 MD5로 해시한 값이에요. PUT은 멤버가 없으면 새로 만들고 있으면 갱신하는 upsert 방식이라 코드가 간결해져요. archive는 멤버를 숨겨두는 보관이고, 영구 삭제(delete-permanent)를 쓰면 개인정보가 완전히 제거되어 다시 가져올 수 없어요.
멤버를 더 세밀하게 관리하고 싶다면 태그(tags), 메모(notes), 목표 이벤트(goals), 활동(activity) 엔드포인트를 함께 활용해요.
GET /lists/{list_id}/members/{subscriber_hash}/tags # 멤버 태그 조회
POST /lists/{list_id}/members/{subscriber_hash}/tags # 멤버 태그 추가/제거
GET /lists/{list_id}/members/{subscriber_hash}/notes # 최근 메모 조회
POST /lists/{list_id}/members/{subscriber_hash}/notes # 메모 추가
GET /lists/{list_id}/members/{subscriber_hash}/activity # 최근 50개 활동(오픈, 클릭, 해지) 조회
세그먼트(segment)
세그먼트는 공통된 필드 정보를 가진 구독자만 모아둔 리스트의 일부예요. 태그(tag)는 연락처를 정리하기 위해 만드는 라벨이고요. 세그먼트와 태그를 조합하면 타깃팅한 캠페인을 보내기 쉬워져요.
GET /lists/{list_id}/segments # 리스트의 모든 세그먼트 조회
POST /lists/{list_id}/segments # 새 세그먼트 생성
GET /lists/{list_id}/segments/{segment_id} # 특정 세그먼트 정보 조회
PATCH /lists/{list_id}/segments/{segment_id} # 세그먼트 수정
DELETE /lists/{list_id}/segments/{segment_id} # 세그먼트 삭제
POST /lists/{list_id}/segments/{segment_id} # 정적 세그먼트 멤버 일괄 추가/제거
세그먼트 안의 멤버는 별도 엔드포인트로 관리해요. 정적(static) 세그먼트만 멤버를 직접 추가하거나 뺄 수 있어요.
GET /lists/{list_id}/segments/{segment_id}/members # 세그먼트 내 멤버 조회
POST /lists/{list_id}/segments/{segment_id}/members # 멤버를 정적 세그먼트에 추가
DELETE /lists/{list_id}/segments/{segment_id}/members/{subscriber_hash} # 세그먼트에서 제거
가입 폼과 웹훅
리스트에는 가입 폼(signup form)을 붙여서 새 구독자를 모을 수 있고, 웹훅(webhook)으로 이벤트를 받아올 수도 있어요.
GET /lists/{list_id}/signup-forms # 리스트의 가입 폼 조회
POST /lists/{list_id}/signup-forms # 기본 가입 폼 커스터마이즈
GET /lists/{list_id}/webhooks # 리스트의 모든 웹훅 조회
POST /lists/{list_id}/webhooks # 새 웹훅 생성
PATCH /lists/{list_id}/webhooks/{webhook_id} # 웹훅 설정 수정
DELETE /lists/{list_id}/webhooks/{webhook_id} # 웹훅 삭제
부가 데이터 확인하기
리스트 성장과 구독자 특성도 살펴볼 수 있어요. 월별 성장 히스토리, 관심 카테고리(그룹), 이메일 클라이언트 통계, IP 지오코딩 기반 위치 정보 등을 조회하고 관리해요.
GET /lists/{list_id}/growth-history # 월별 성장 요약
GET /lists/{list_id}/interest-categories # 관심 카테고리(그룹 제목) 조회
GET /lists/{list_id}/clients # 인기 이메일 클라이언트 통계
GET /lists/{list_id}/locations # 구독자 위치(국가) 목록
GET /lists/{list_id}/{list_id}/tag-search # 이름으로 태그 검색
사용 예시
전체 리스트를 조회하고, 오디언스에 멤버를 등록하는 흐름으로 정리하면 이렇게 돼요. API 키는 Authorization: Bearer 헤더로 보내요.
# 계정의 모든 리스트 조회
curl -sL "https://<dc>.api.mailchimp.com/3.0/lists" \
-u "anystring:YOUR_API_KEY"
# 특정 리스트에 새 멤버 추가 (JSON body)
curl -sL "https://<dc>.api.mailchimp.com/3.0/lists/{list_id}/members" \
-u "anystring:YOUR_API_KEY" \
-d '{"email_address":"[email protected]","status":"subscribed"}'
<dc>(data center)와 API 키는 Mailchimp 계정의 API 키에서 확인할 수 있고, 모든 응답은 JSON으로 돌아와요. 더 자세한 파라미터는 공식 문서를 참고해 주세요.