뉴스레터 API

뉴스레터 API는 이메일 뉴스레터의 구독자 명단과 캠페인(작성 → 예약·발송 → 취소)을 관리합니다. 구독자·캠페인 엔드포인트는 대시보드 API 계열로, Authorization: Bearer 헤더에 JWT 액세스 토큰을 담아 호출합니다. 토큰 발급과 역할(RBAC)은 대시보드 인증을 참고하세요. 수신거부 엔드포인트는 알림 API 계열의 무인증 공개 엔드포인트로 이메일 본문의 수신거부 링크가 호출하며, 지원 채널은 현재 email 하나입니다.

권한 경계

캠페인 상태

• 발송을 트리거하면 draft → sending(즉시) 또는 draft → scheduled → sending(예약)으로 전이하며, scheduled / sending은 취소 API로 canceled가 될 수 있습니다.
• sending(또는 scheduled) → sent 전이는 캠페인 상세 조회 시점에 판정됩니다. 대기 중인 요청(queued + processing)이 0이 되면 조회 시 sent로 전이되고 finishedAt이 기록됩니다.

구독자 동의 상태

동의 상태를 전이하면 정보통신망법 대응을 위한 시각이 자동 기록됩니다. subscribed로 전환하면 consentedAt이 기록되고 unsubscribedAt은 null로 초기화되며, unsubscribed로 전환하면 unsubscribedAt이 기록됩니다.

구독자

구독자 목록 조회

워크스페이스의 구독자 목록을 최신 등록순으로 조회합니다. (역할: owner / admin / operator / viewer)

{ "subscribers": [ { "id": "…", "channel": "email", "address": "user@example.com", "…": "…" } ], "total": 120, "limit": 50, "offset": 0 }

구독자 단건 조회

구독자 1명을 조회합니다. 응답은 { "subscriber": { … } } 형태이며, 워크스페이스에 해당 ID의 구독자가 없으면 404가 반환됩니다. (역할: owner / admin / operator / viewer)

구독자 생성

구독자 1명을 등록합니다. (역할: owner / admin / operator)

등록 시 주소 도메인의 MX(폴백 A) 레코드를 DNS로 조회해 수신 가능성을 검증하며, 구독자마다 수신거부 토큰이 자동 발급됩니다.

curl -X POST https://api.posmit.io/v1/newsletter/subscribers \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "address": "user@example.com",
    "name": "홍길동",
    "attributes": { "등급": "VIP" }
  }'

구독자 일괄 등록(임포트)

여러 구독자를 한 번에 등록·갱신합니다. (역할: owner / admin / operator)

같은 채널·주소의 구독자가 이미 있으면 갱신(updated), 없으면 생성(created)되며, 형식 오류 등 개별 항목의 실패는 전체를 막지 않고 건너뛰어 skipped로 집계됩니다. 주소는 단건 생성과 동일하게 소문자로 정규화되지만, MX 레코드 검증은 수행하지 않습니다.

{ "total": 1000, "created": 830, "updated": 150, "skipped": 20 }

구독자 수정

구독자의 name / consentStatus / consentSource / attributes를 수정합니다. (역할: owner / admin / operator) channel과 address는 변경할 수 없으며 이 필드를 보내면 400, 구독자가 없으면 404가 반환됩니다. consentStatus 변경 시 consentedAt / unsubscribedAt이 자동 기록됩니다.

구독자 삭제

구독자를 삭제하며, 성공 시 본문 없이 204가 반환됩니다. (역할: owner / admin)

캠페인

캠페인 목록 조회

캠페인 목록을 최신 생성순으로 조회합니다. (역할: owner / admin / operator / viewer) 쿼리는 status(상태 필터), limit(1~200, 기본 50), offset(기본 0)을 지원하며, 응답은 { "campaigns": […], "total": …, "limit": …, "offset": … } 형태입니다.

캠페인 상세 조회

캠페인 1건을 발송 집계와 함께 조회합니다. (역할: owner / admin / operator / viewer)

{
  "campaign": {
    "id": "…", "name": "7월 뉴스레터", "channel": "email", "status": "sending",
    "totalRecipients": 1200, "queuedCount": 1195, "failedCount": 5, "audienceSize": 1210,
    "deliveryStats": { "queued": 300, "processing": 20, "sent": 860, "failed": 15 }, "…": "…"
  }
}

• totalRecipients / queuedCount / failedCount는 팬아웃 진행 상황이 배치마다 반영되는 카운터입니다.
• deliveryStats는 수신자별 발송 요청의 상태별 집계입니다 (queued / processing / sent / failed / canceled, unknown은 요청 미생성).
• audienceSize는 현재 세그먼트 조건에 맞는 발송 대상 수로, 발송 시점과 다를 수 있습니다. 이 조회 시점에 대기 요청이 0이면 캠페인이 sent로 지연 전이됩니다.

발송 대상 미리보기

발송 전에 세그먼트 조건에 맞는 대상 수를 확인합니다. 응답은 { "audienceSize": 1210 }입니다. (역할: owner / admin / operator / viewer)

캠페인 생성

캠페인을 draft 상태로 생성합니다. (역할: owner / admin / operator)

캠페인 수정

캠페인을 수정합니다. draft 상태에서만 가능합니다. (역할: owner / admin / operator) 생성과 같은 필드를 부분 수정할 수 있으나 channel은 변경할 수 없습니다(보내면 400). scheduledAt에 null을 보내면 예약이 해제됩니다.

캠페인 발송

캠페인 발송을 트리거합니다. draft / scheduled 상태에서만 가능합니다. (역할: owner / admin / operator)

발송 대상 산정 규칙 — 다음을 모두 만족하는 구독자가 대상입니다. 캠페인과 같은 channel이고, consentStatus가 subscribed이며, 이메일 수신 차단 목록(영구 반송·수신자 불만으로 등록된 suppression 주소)에 없고, audienceFilter.attributes의 모든 key-value를 구독자 attributes가 포함(containment 매칭)해야 합니다.

audienceFilter는 { "attributes": { "키": "값" } } 형태이며, 값으로 문자열·숫자·불리언을 쓸 수 있고 숫자·불리언은 문자열로 변환되어 매칭됩니다.

검증 후 팬아웃 잡을 큐에 적재하고 즉시 반환하며, 실제 수신자별 요청 생성은 워커가 비동기로 수행합니다. 워커는 구독자를 500명 배치로 읽어 배치 안에서 20건씩 동시 처리하고, 진행 카운터를 배치마다 캠페인에 반영합니다. 팬아웃은 멱등해서 잡이 재시도되어도 이미 큐에 적재된 구독자는 건너뛰므로 중복 발송되지 않습니다.

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

{ "campaignId": "…", "status": "scheduled", "audienceSize": 1210, "scheduledAt": "2026-07-15T09:00:00.000Z", "fanoutJobId": "1024" }

캠페인 취소

발송을 취소합니다. scheduled / sending 상태에서만 가능하며, 그 외 상태에서는 409가 반환됩니다. (역할: owner / admin / operator) 아직 실행되지 않은 예약 팬아웃 잡을 제거하고, 이미 생성된 발송 요청 중 종료되지 않은 건(sent / failed / canceled 제외)을 취소하지만, 이미 전달 완료된 메일은 되돌릴 수 없습니다.

{ "campaignId": "…", "status": "canceled", "canceledRequests": 850 }

캠페인 삭제

캠페인을 삭제합니다. draft / canceled / failed 상태에서만 가능하며, 성공 시 204가 반환됩니다. (역할: owner / admin) scheduled / sending / sent 캠페인은 삭제할 수 없고(409), 예약·발송 중이라면 먼저 취소해야 합니다.

수신거부 (공개 엔드포인트)

수신거부 엔드포인트는 인증이 없으며, 이메일 footer의 수신거부 링크에 포함된 토큰이 구독자를 식별·인가합니다. 수신거부가 확정되면 구독자의 consentStatus가 unsubscribed로 바뀌고 unsubscribedAt이 기록됩니다.

수신거부 확인 페이지 (GET)

수신거부 링크 클릭 시 호출되어 HTML 확인 페이지를 반환하며, 이 요청만으로는 수신거부가 처리되지 않습니다. 페이지의 확인 버튼이 아래 확정 엔드포인트로 token을 POST합니다. 토큰이 없거나 형식이 잘못되어도 정보 노출을 피하기 위해 에러 대신 항상 200과 안내 페이지(“수신거부 링크가 유효하지 않습니다”)를 반환합니다.

수신거부 확정 — 폼 (POST)

확인 페이지의 폼이 제출하는 엔드포인트로, 수신거부를 처리하고 HTML 결과 페이지를 반환합니다. 본문은 application/x-www-form-urlencoded 형식의 token 한 필드이며, 토큰이 유효하지 않아도 항상 200과 안내 페이지를 반환합니다.

수신거부 확정 — 프로그램적 (POST)

List-Unsubscribe의 원클릭 수신거부 등 프로그램적 호출에 사용하는 JSON 엔드포인트로, 이 호출은 수신거부를 즉시 확정합니다.

{ "data": { "unsubscribed": true }, "meta": { "timestamp": "2026-07-11T09:00:00.000Z" } }

토큰이 유효하지 않으면 200에 "unsubscribed": false가 반환됩니다. 이미 수신거부된 구독자의 토큰은 true를 반환하며 멱등하게 동작합니다. 두 POST 엔드포인트 모두 token이 비어 있거나 64자를 초과하면 400으로 거부되며, 이는 형식이 맞는 토큰이 단지 존재하지 않는 경우(200)와 구분됩니다.

대시보드 화면에서의 구독자 관리·캠페인 발송 사용법은 가이드 › 뉴스레터를 참고하세요.