뉴스레터

뉴스레터는 구독자 목록을 대상으로 대량 이메일 캠페인을 보내는 기능입니다. 현재 이메일 채널 전용이며, 대시보드 뉴스레터 › 구독자 / 캠페인 메뉴에서 관리합니다.

권한 경계는 다음과 같습니다.

구독자 관리

구독자는 주소(address), 이름(name), 동의 상태(consentStatus), 자유 속성(attributes)으로 구성됩니다.

• 동의 상태가 subscribed로 바뀌면 consentedAt, unsubscribed로 바뀌면 unsubscribedAt이 자동 기록됩니다. 정보통신망법상 동의 이력 요건을 위한 것입니다.
• 구독자마다 수신거부 토큰이 자동 발급되어, 캠페인 본문의 수신거부 링크에 사용됩니다.

단건 등록 예시입니다.

curl -X POST https://api.posmit.io/v1/newsletter/subscribers \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "address": "user@example.com",
    "name": "홍길동",
    "consentStatus": "subscribed",
    "consentSource": "signup-form",
    "attributes": { "등급": "VIP", "지역": "서울" }
  }'

목록 조회는 동의 상태 필터와 주소·이름 부분 검색을 지원합니다.

curl "https://api.posmit.io/v1/newsletter/subscribers?consentStatus=subscribed&search=example.com&limit=50" \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN"

CSV 임포트

대시보드 구독자 화면의 “CSV 임포트”로 최대 5,000건을 한 번에 등록할 수 있습니다.

CSV 규칙은 다음과 같습니다.

• 첫 줄은 헤더입니다. 표준 컬럼(대소문자 무시): channel(별칭 채널), address(별칭 email, 주소, 이메일), name(별칭 이름, 성명).
• 표준 컬럼이 아닌 나머지 컬럼은 전부 구독자 속성(attributes)으로 저장됩니다. 뒤에서 설명할 속성 필터의 재료가 됩니다.
• channel 값은 email(별칭 메일)만 허용됩니다. 그 외 값의 행은 건너뛰며, 오류 목록에 줄 번호가 표시됩니다.
• 따옴표로 감싼 필드와 이스케이프("")를 지원합니다.

channel,address,name,등급,지역
email,kim@example.com,김철수,VIP,서울
email,lee@example.com,이영희,일반,부산

임포트 시 동의 상태를 한 번에 지정할 수 있으며(기본 subscribed), 결과는 다음과 같이 집계됩니다.

캠페인 작성

캠페인 상태는 다음 흐름을 따릅니다.

캠페인 생성 예시입니다.

curl -X POST https://api.posmit.io/v1/newsletter/campaigns \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "7월 VIP 프로모션",
    "channel": "email",
    "subject": "{{이름}}님을 위한 7월 혜택 안내",
    "contentText": "{{이름}}님, 이번 달 준비된 혜택을 확인해 보세요.",
    "contentHtml": "<p><b>{{이름}}</b>님, 이번 달 준비된 혜택을 확인해 보세요.</p>",
    "isAdvertisement": true,
    "audienceFilter": { "attributes": { "등급": "VIP" } },
    "scheduledAt": "2026-07-15T10:00:00+09:00"
  }'

• 이메일 캠페인은 subject가 필수입니다.
• 본문의 {{키}} 자리는 발송 시 구독자의 attributes 값으로 치환됩니다(값이 없으면 빈 문자열).
• 수정(PATCH)은 draft 상태에서만 가능하며, 채널은 변경할 수 없습니다.

속성 필터로 대상 좁히기

audienceFilter.attributes에 지정한 key-value를 모두 포함하는 구독자만 발송 대상이 됩니다. 값은 문자열·숫자·불리언을 지원합니다(내부적으로 문자열 비교). CSV 임포트로 넣어 둔 속성을 그대로 쓸 수 있습니다.

발송 전에 대상 수를 미리 확인할 수 있습니다.

curl https://api.posmit.io/v1/newsletter/campaigns/CAMPAIGN_ID/audience \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN"
# → { "audienceSize": 1240 }

발송과 취소

발송

curl -X POST https://api.posmit.io/v1/newsletter/campaigns/CAMPAIGN_ID/send \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "scheduledAt": "2026-07-15T10:00:00+09:00" }'

• scheduledAt을 생략하면 캠페인에 저장된 예약 시각(미래일 때)을 쓰고, 그것도 없으면 즉시 발송합니다.
• draft·scheduled 상태에서만 발송할 수 있습니다(그 외 409). 대상이 0명이면 400 에러입니다.
• 발송은 비동기 팬아웃입니다. 요청은 대상 검증 후 즉시 반환되고, 백그라운드 워커가 배치 500명 × 동시 20건으로 개별 발송 요청을 만들어 기존 발송 파이프라인 큐에 적재합니다. 팬아웃은 멱등이라 재시도해도 같은 구독자에게 중복 적재되지 않습니다.

실제 발송 대상은 다음 조건을 모두 만족하는 구독자입니다.

1. 채널이 일치하고 동의 상태가 subscribed
2. 이메일 suppression 목록에 없는 주소 — 반송(hard bounce)·수신자 불만(complaint)으로 차단된 주소는 자동 제외됩니다. (이메일 발송(SES) 참고)
3. audienceFilter 속성 조건 일치

진행 상황은 캠페인 상세의 totalRecipients / queuedCount / failedCount와 상태별 전송 집계(deliveryStats)로 확인할 수 있습니다.

취소

curl -X POST https://api.posmit.io/v1/newsletter/campaigns/CAMPAIGN_ID/cancel \
  -H "Authorization: Bearer YOUR_DASHBOARD_TOKEN"

• scheduled 또는 sending 상태에서만 취소할 수 있습니다(그 외 409).
• 아직 실행되지 않은 팬아웃 잡이 제거되고, 이미 큐에 들어간 발송 요청은 canceled 처리됩니다. 응답의 canceledRequests로 취소된 건수를 확인할 수 있습니다.
• 이미 공급자로 전달된 메일은 되돌릴 수 없습니다.
• 캠페인 삭제는 draft / canceled / failed 상태에서만 가능합니다. 진행 중인 캠페인은 먼저 취소해야 합니다.

수신거부 처리

발송되는 메일의 footer에는 구독자별 토큰이 담긴 수신거부 링크가 포함됩니다.

• 링크 클릭: GET /v1/newsletter/unsubscribe?token=... — 인증 없이 토큰만으로 즉시 수신거부 처리되고, 한국어 확인 페이지(“수신거부가 완료되었습니다”)가 표시됩니다. 실패 시(만료·위조 토큰) 안내 페이지가 표시됩니다.
• 프로그램 처리: POST /v1/newsletter/unsubscribe body { "token": "..." } — 메일 클라이언트의 List-Unsubscribe 원클릭 처리 등에 사용되며 { "data": { "unsubscribed": true }, "meta": { "timestamp": "..." } }를 반환합니다.

수신거부된 구독자는 consentStatus가 unsubscribed로 바뀌고 unsubscribedAt이 기록되며, 이후 캠페인 대상에서 자동 제외됩니다.

다음 단계