Brevo 데이터 내보내기와 마이그레이션: 데이터를 넣고 빼는 방법

“brevo data export migration to another platform” 같은 검색어의 검색량은 하나의 걱정에서 나옵니다. 쌓아 온 데이터가 넣기는 쉬워도 빼기는 어렵지 않을까 하는 걱정입니다. Brevo에 대한 솔직한 답은 이렇습니다. 대부분은 깔끔하게 나오고, 일부는 다시 만들어야 하는 형태로 나오며, 작지만 중요한 일부는 아예 옮길 수 없습니다.

이 가이드는 양방향을 모두 다룹니다. 정확히 무엇이 내보내지고 무엇이 내보내지지 않는지, 인터페이스로 감당하기 어려운 대형 계정을 위한 API 호출은 무엇인지, 그리고 수신거부 목록과 발신 평판을 뒷전이 아니라 일급 관심사로 다루는 마이그레이션 체크리스트를 제시합니다.

Brevo에서 실제로 내보낼 수 있는 것

연락처와 속성

화면 경로는 CRM에서 Contacts로 이동하는 것입니다. 데이터베이스 전체를 내보내려면 리스트나 세그먼트가 적용되어 있지 않고 필터도 걸려 있지 않은지 확인하십시오. 특정 리스트나 세그먼트만 내보내려면 먼저 “Load a list or segment”를 클릭해 선택합니다.

그다음 어떤 표준 속성과 커스텀 속성을 포함할지 고릅니다. EMAIL, 최종 변경일, 생성일은 기본으로 선택되어 있고 나머지는 직접 추가해야 하는데, 사람들이 가장 자주 놓치는 단계가 바로 이 부분입니다. CSV 필드 구분자로 세미콜론이나 쉼표를 고르고, 필요하다면 “Send export by email”을 켜서 계정 소유자 주소로 다운로드 링크가 가도록 설정하십시오. “Start export”를 클릭한 뒤 계정 이름 옆의 알림 종 모양 아이콘에서 파일을 내려받습니다.

리스트와 세그먼트

리스트는 소속 정보 형태로 내보내집니다. 리스트별로 한 번씩 내보내거나, 전체 내보내기 한 번에 _listIds 메타데이터를 포함시킨 뒤 파일을 나중에 나누면 됩니다. GET /v3/contacts/lists 는 리스트 이름과 ID, 폴더 ID를 제공하므로 반대편에서 구조를 그대로 재현할 수 있습니다.

세그먼트는 다릅니다. 그리고 이것이 첫 번째 실질적인 공백입니다. GET /v3/contacts/segments 는 id, segmentName, categoryName, updatedAt 만 반환합니다. 세그먼트를 정의하는 필터 조건은 노출되지 않습니다. 특정 시점의 세그먼트 구성원은 내보낼 수 있지만, 그 구성원을 만들어 낸 규칙은 화면을 보고 읽어서 새 도구에서 직접 다시 만들어야 합니다. 계정을 해지하기 전에 모든 세그먼트를 화면 캡처해 두시기 바랍니다.

캠페인 통계

캠페인 리포트에서는 데이터를 CSV로 내보낼 수 있고, 이메일과 SMS 리포트는 공유나 인쇄를 위한 PDF 버전도 제공합니다. 전체 이력을 한꺼번에 가져오려면 GET /v3/emailCampaigns 를 사용하십시오. 이 엔드포인트는 globalStats, linksStats, statsByDomain 값을 갖는 statistics 파라미터와 최대 2년 범위를 커버하는 startDate, endDate 쌍을 받습니다.

트랜잭션 로그

경로는 두 가지이고, 조회 가능한 기간이 서로 다릅니다.

GET /v3/smtp/statistics/events 는 유형별로 필터링된 개별 이벤트를 반환합니다(delivered, opened, clicks, hardBounces, spam, unsubscribed 등). 날짜 범위는 90일을 넘을 수 없으며, 범위와 days 파라미터를 모두 주지 않으면 최근 30일이 기본값입니다.

대량 처리는 POST /v3/webhooks/export 로 합니다. 최근 7일간의 원시 이벤트에 대한 내보내기 작업을 생성하며, 7일 기간당 최대 20개의 작업으로 제한됩니다. processId를 반환하고 완료 시 알림 URL을 호출하며, date, email, event, message-id, reason, sending_ip, subject, tag, template_id 등의 열을 담은 CSV를 전달합니다. 용량이 크면 여러 CSV 파일을 담은 압축 파일로 도착합니다.

실무적 결론은 이렇습니다. 90일보다 오래된 트랜잭션 이력이 필요하다면, 진작부터 정기적으로 내보내고 있었어야 합니다. 떠나기로 결심한 그 주가 아니라 지금 그 작업을 설정하시기 바랍니다.

함께 가져갈 수 없는 것

대부분의 마이그레이션 가이드가 건너뛰는 부분입니다.

• 자동화 워크플로 구조. API는 이벤트를 통해 자동화를 트리거할 수 있지만, 워크플로의 분기와 지연, 조건을 다시 읽어 오는 문서화된 엔드포인트는 없습니다. 모든 워크플로는 새 플랫폼에서 수동으로 다시 만들어야 합니다.
• 세그먼트 필터 정의. 위에서 설명한 대로 이름과 현재 구성원만 조회할 수 있습니다.
• 연락처별 전체 참여 이력. 내보내기 엔드포인트의 customContactFilter 를 사용하면 특정 캠페인의 오픈, 클릭, 미오픈, 수신거부, 하드 바운스, 소프트 바운스 대상자를 내보낼 수 있습니다. 하지만 “이 연락처가 지금까지 만든 모든 오픈과 클릭”을 담은 하나의 깔끔한 파일은 얻을 수 없습니다. 원시 이벤트 엔드포인트가 90일로 제한되기 때문입니다.
• 템플릿 렌더링 정확도. htmlContent 는 깔끔하게 내보내지지만, 드래그 앤 드롭 블록과 병합 태그 문법, 수신거부 링크 자리표시자는 플랫폼마다 다릅니다. 내보낸 HTML은 완성된 템플릿이 아니라 출발점입니다. 새 편집기에서 모든 템플릿을 다시 테스트할 시간을 확보하십시오.
• 도달률 평판. 발신자 평판은 발신 IP와 인증된 도메인에 붙어 있습니다. 새 플랫폼이면 새 IP 풀이고, 새 워밍업입니다. 같은 도메인과 DKIM 설정을 유지하면 평판의 도메인 쪽은 보존되어 실제로 도움이 되지만, IP 쪽은 함께 오지 않습니다.
• 폼, 랜딩 페이지, 추적 식별자. 가입 폼과 랜딩 페이지, 추적 스크립트는 모두 플랫폼 고유의 ID를 가집니다. 사이트에 삽입된 것은 전부 교체해야 하고, 그 ID에 묶인 분석은 전환 시점에 끊깁니다.

대형 계정을 위한 스크립트 내보내기

연락처가 대략 10만 명을 넘어가면 화면 내보내기는 느리고 번거로워지며, 어차피 반복 실행 가능한 작업이 필요해집니다. 연락처 내보내기 엔드포인트는 비동기 방식입니다. 필터를 받아서 프로세스 ID를 반환하고, 완료되면 CSV를 전달합니다.

curl --request POST \
  --url https://api.brevo.com/v3/contacts/export \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "customContactFilter": { "actionForContacts": "allContacts" },
    "exportMandatoryAttributes": true,
    "exportAttributes": ["FIRSTNAME", "LASTNAME", "SMS", "COUNTRY"],
    "exportMetadata": ["_listIds", "ADDED_TIME", "MODIFIED_TIME"],
    "exportSubscriptionStatus": ["email_marketing", "sms_marketing"],
    "exportDateInUTC": true,
    "notifyUrl": "https://example.com/hooks/brevo-export"
  }'

호출에 성공하면 HTTP 202와 함께 processId를 담은 본문이 반환됩니다. exportMandatoryAttributes 는 기본값이 true이며 EMAIL, ADDED_TIME, MODIFIED_TIME 을 포함하므로, 커스텀 필드는 exportAttributes 에 지정합니다. 이메일과 SMS의 마케팅 수신 동의 상태를 파일에 담아 주는 것은 exportSubscriptionStatus 설정이며, 이를 빠뜨리는 것이 규정 준수 마이그레이션에 쓸모없는 내보내기를 만드는 가장 흔한 원인입니다.

작업 완료를 기다리는 대신 레코드를 순회하고 싶다면, GET /v3/contacts 가 offset 과 함께 최대 1000까지의 limit 을 받고 증분 조회를 위한 modifiedSince, createdSince 도 지원합니다. 각 연락처에는 emailBlacklisted, smsBlacklisted, listIds, listUnsubscribed, consentGroups 가 함께 돌아오므로 동의 상태를 재구성하는 데 필요한 정보가 모두 포함됩니다.

스크립트를 작성할 때는 요청 제한을 주시하십시오. 연락처 엔드포인트는 표준 요금제에서 시간당 36,000회, 초당 10회를 허용하고 Professional과 Enterprise 등급에서는 두 배가 되지만, 대부분의 다른 엔드포인트는 시간당 100회에 머뭅니다. 연락처 100만 명을 페이지당 1000건으로 넘기면 1000회 요청이라 연락처 예산 안에 여유롭게 들어가지만, 캠페인이나 템플릿 엔드포인트를 반복문에서 두드리는 것은 그렇지 않습니다.

수신거부 목록을 가장 먼저 옮겨야 하는 이유

다른 무엇보다 수신거부부터 옮기십시오.

법적 근거는 단순합니다. 수신을 거부한 고객은 브랜드에 대한 동의를 철회한 것입니다. 그 철회는 벤더를 바꿨다고 해서 초기화되지 않습니다. GDPR에서 동의와 그 철회의 기록은 컨트롤러로서의 의무이며, CAN-SPAM에서 수신거부는 영업일 10일 이내에 처리되어야 하고 이후에도 무기한 유지되어야 합니다. 마이그레이션 중에 목록을 잃는 것은 기술적 사고가 아니라, 책임 소재가 명확히 남는 규정 위반입니다.

실무적으로는 도달률 측면이 더 심각합니다. 억제된 주소는 불만을 제기했거나 하드 바운스였거나 적극적으로 수신을 원하지 않았던 사람들이 불균형하게 많습니다. 평판이 전혀 없는 새 IP로 이들에게 메일을 보내는 것은 새로 구축한 발송 환경을 첫 주에 제한하거나 차단당하게 만드는 가장 확실한 방법입니다. 재활용된 스팸 트랩과 불만 제기자 몇천 명이면 한 달간의 신중한 워밍업이 무너집니다.

따라서 억제 대상을 암묵적으로 포함되기를 기대하지 말고 명시적으로 내보내십시오. 내보내기 엔드포인트에서 actionForContacts 는 어떤 경로로든 차단된 연락처를 위한 unsubscribed 와 특정 리스트에서 수신을 거부한 연락처를 위한 unsubscribedPerList 를 받습니다. 캠페인별 hardBounces 는 따로 한 번 더 내보내십시오. 새 플랫폼에 들어갈 때는 그 파일을 발송 가능한 리스트가 아니라 억제 목록으로 가져와야 합니다.

Brevo는 반대 방향도 지원합니다. 차단된 연락처 목록 가져오기를 지원하며, 가져오기 API는 emailBlacklist 와 smsBlacklist 불리언을 받아서 가져온 파일이 억제 상태로 들어가게 합니다. 여기에 Brevo가 옳게 강제하는 비대칭이 하나 있습니다. 연락처는 일괄로 차단 해제할 수 없습니다. 그냥 두라고 요청한 사람을 일괄로 재구독시키는 것은 불법이기 때문입니다. 억제는 추가하기는 쉽고 제거하기는 의도적으로 어렵습니다. 이를 장애물이 아니라 올바른 동작으로 받아들이시기 바랍니다.

마이그레이션 체크리스트, Brevo에서 나갈 때

1. 점검. 연락처, 리스트, 세그먼트, 활성 자동화, 템플릿, 연동의 수를 세십시오. 어떤 연동이 Brevo에 데이터를 쓰고 있는지 적어 두십시오. 그것들이 방향을 다시 잡아야 할 배관입니다.
2. 내보내기. 모든 속성과 구독 상태를 포함한 연락처, 리스트별 파일 또는 _listIds 를 담은 단일 파일, 별도 파일로 분리한 억제 대상, 캠페인 통계, 90일 창이 허용하는 만큼의 트랜잭션 이벤트, 그리고 템플릿 HTML.
3. 만료되는 것부터 보관. 기간 제한이 있는 항목(원시 이벤트, 로그)은 창이 지나면 사라집니다. 지금 자체 데이터 웨어하우스나 오브젝트 스토리지에 저장하십시오.
4. 정리와 매핑. 중복을 제거하고 날짜와 전화번호 형식을 표준화한 뒤, 새 플랫폼을 위한 열 대 필드 매핑을 명시적으로 작성하십시오. 이 시점은 1년간 반응이 없던 주소를 정리하기에도 자연스러운 순간입니다. 죽은 무게를 워밍업하는 비용을 치르는 것보다 낫습니다. 기준값은 이메일 리스트 정리 가이드에서 다룹니다.
5. 억제 목록 먼저 적재. 수신거부와 하드 바운스를 새 플랫폼의 억제 목록으로 가져오고, 건수가 내보내기와 일치하는지 확인한 다음에야 발송 가능한 연락처를 적재하십시오.
6. 워밍업. 가장 반응이 좋은 세그먼트부터 시작해 볼륨을 점진적으로 늘리고, 반송률과 불만율을 매일 확인하십시오. 이메일 도달률 가이드에 그 순서가 자세히 나와 있습니다.
7. 병행 운영. 새 플랫폼이 마케팅 발송의 비중을 점차 늘려 가는 동안 Brevo는 계속 살려 두고 핵심 트랜잭션 메일을 보내게 하십시오. 두 가지를 동시에 전환하지 마십시오.
8. 검증. 연락처 수를 대조하고, 20건 정도를 필드 단위로 표본 점검하고, 테스트 발송을 시도해 억제된 연락처가 실제로 억제되는지 확인하고, 일주일치 발송량을 이전 플랫폼과 비교하십시오.
9. 전환과 롤백 준비. DNS와 연동 엔드포인트는 지켜보는 사람이 있는 시간대에 변경하십시오. 전환 후 최소 한 번의 전체 청구 주기 동안 Brevo 계정을 결제 상태로 유지하고, 내보낸 파일은 두 플랫폼 바깥에 보관하십시오. 벤더의 약속이 아니라 그것이 실제 롤백 계획입니다.

다른 플랫폼에서 Brevo로 옮겨 올 때

같은 체크리스트를 반대로 실행하되, Brevo에 특화된 세 가지를 유념하십시오.

기존 벤더에서 제대로 된 내보내기를 받으십시오. 대부분의 플랫폼은 연락처와 커스텀 필드를 CSV로 제공합니다. 억제 목록과 반송 목록은 별도 내보내기인 경우가 많아 요청을 깜빡하기 쉬우니 명시적으로 요구하십시오. 연락처 수 기반 과금 모델에서 넘어오는 경우라면, 실제로 지불하게 될 금액을 Brevo 요금제 가이드와 비교해 보십시오.

업로드 전에 필드를 매핑하십시오. Brevo 속성에는 타입(텍스트, 숫자, 날짜, 불리언, 카테고리)이 있으며, 날짜가 텍스트 속성에 들어가면 나중에 필터링할 수 없습니다. 올바른 타입으로 속성을 먼저 만든 다음 가져오십시오.

규모가 있는 작업은 API로 가져오십시오. POST /v3/contacts/import 는 fileBody 의 인라인 CSV, jsonBody 의 JSON 배열(둘 다 약 10 MB 제한), 또는 fileUrl 을 통한 원격 파일과 listIds 또는 newList 객체를 받습니다. updateExistingContacts 는 기본값이 true이며 이메일로 매칭합니다. 억제 파일은 emailBlacklist 를 true로 설정해 한 번 가져오고, 발송 가능한 연락처는 두 번째 가져오기로 처리하십시오. 실제로 동작하는 전체 스크립트는 스크립트로 Brevo에 CSV 연락처 가져오기 가이드에 있습니다.

그다음에는 옮겨지지 않은 것들, 즉 자동화, 세그먼트, 폼, 템플릿을 다시 만드십시오. 실제 고객에게 보내기 전에 여러 메일 사업자의 시드 주소로 테스트 발송을 해 보시기 바랍니다.

다음 마이그레이션은 절벽이 되지 않도록

플랫폼 마이그레이션이 절벽처럼 느껴지는 이유는 그 플랫폼이 기록의 원천이 되어 버렸기 때문입니다. 주문 이력, 구독자 상태, 캠페인 결과가 한 벤더 안에 살고 있으니, 옮긴다는 것은 곧 대피를 뜻합니다.

대안은 자체 원천 데이터를 보유하고 발송 플랫폼을 금고가 아니라 목적지로 두는 것입니다. 스토어 데이터, 동의 상태, 참여 이벤트가 자체 시스템으로 지속적으로 동기화된다면, 채널을 바꾸거나 추가하는 일은 프로젝트가 아니라 설정 변경이 됩니다. Tajo가 Brevo와 판매자의 기술 스택 사이에서 하는 일이 바로 그것입니다. 데이터가 양방향으로 계속 흐르게 해서 플랫폼이 유일한 사본이 되지 않도록 합니다.

어느 쪽이든, 위에서 설명한 내보내기 작업은 떠날 계획이 있든 없든 지금 정기 실행으로 걸어 둘 가치가 있습니다. 가장 저렴한 마이그레이션은 결심하는 순간 데이터가 이미 플랫폼 바깥에 있는 경우입니다.