수신거부 동기화 API 레퍼런스

080·수신거부 링크로 수집된 수신거부 목록을 내려받고, 자사에서 받은 수신거부를 등록·정정 (7개 엔드포인트)

커서 규약

목록은 커서(cursor) 방식입니다. 페이지 번호가 아니라 "여기까지 받았다"는 표식을 주고받습니다. 응답의 nextCursor를 저장해 두었다가 다음 호출에 그대로 넘기면 그 이후 신규분만 받습니다.

• 커서는 불투명한 문자열입니다. 내부 값을 해석하거나 직접 만들지 마세요.
• 채널이 다른 커서를 넘기면 400으로 거절합니다.
• 총건수는 목록 응답에 없습니다. 필요하면 워터마크를 쓰세요.
• 등록 직후 몇 초간은 목록에 나타나지 않을 수 있습니다(정합성 보정). 다음 호출에서 반드시 포함됩니다.

GET /api/v1/service/messaging/unsubscribes

커서 이후의 수신거부를 오래된 것부터 내려줍니다.

curl "https://fplink.net/api/v1/service/messaging/unsubscribes?channel=SMS&limit=500" \
  -H "X-API-KEY: YOUR_API_KEY"

{
  "channel": "SMS",
  "items": [
    {
      "id": 84213,
      "channel": "SMS",
      "phone": "01012345678",
      "method": "080",
      "source": "080:0801234567",
      "unsubscribedAt": "2026-09-04T02:11:00Z"
    }
  ],
  "nextCursor": "U01TOjg0MjEz",
  "hasMore": true
}

hasMore가 true인 동안 nextCursor를 넘겨 반복 호출하면 전체를 받을 수 있습니다. method는 080(무료 전화), LINK(수신거부 링크), CSV(콘솔 등록) 등입니다.

GET /api/v1/service/messaging/unsubscribes/watermark

현재 최신 커서입니다. 저장해 둔 커서와 값이 같으면 받을 것이 없다는 뜻이므로 목록을 호출하지 않아도 됩니다. 주기적으로 확인만 하는 용도라면 이 엔드포인트를 먼저 호출하세요.

{
  "channel": "SMS",
  "latestCursor": "U01TOjg0MjEz",
  "asOf": "2026-09-04T02:20:11Z"
}

GET /api/v1/service/messaging/unsubscribes/deletions

삭제된 수신거부 항목입니다. 목록 API는 존재하는 항목만 내려주므로, 잘못 등록된 건을 정정 삭제한 사실은 이 피드로만 알 수 있습니다. 커서 사용법은 목록과 같습니다.

{
  "channel": "SMS",
  "items": [
    { "id": 12, "channel": "SMS", "phone": "01012345678", "sourceId": 84213, "deletedAt": "2026-09-05T01:00:00Z" }
  ],
  "nextCursor": "U01TOjEy",
  "hasMore": false
}

권장 동기화 절차

1. 최초 1회: 커서 없이 /unsubscribes를 hasMore=false가 될 때까지 반복 호출해 전체를 받습니다.
2. 주기 실행(예: 5분): /watermark를 호출해 저장한 커서와 비교합니다. 같으면 종료합니다.
3. 다르면 /unsubscribes?cursor=로 신규분을 받고 커서를 갱신합니다.
4. 이어서 /deletions?cursor=로 삭제분을 받아 sourceId가 일치하는 항목만 지웁니다.

등록·삭제

자사 CRM·콜센터에서 접수한 수신거부를 저희 쪽에도 반영할 때 씁니다. 등록하면 그 시점부터 저희를 통한 광고성 발송에서 자동으로 제외됩니다.

POST /api/v1/service/messaging/unsubscribes

curl -X POST https://fplink.net/api/v1/service/messaging/unsubscribes \
  -H "X-API-KEY: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel":"SMS","value":"010-1234-5678","source":"crm"}'

unsubscribedAt(선택)으로 실제 거부 시점을 지정할 수 있습니다. 없으면 요청 시각으로 기록합니다. 이미 등록된 값이면 duplicated로 응답하며 오류가 아닙니다.

POST /api/v1/service/messaging/unsubscribes/bulk

요청당 최대 1,000건입니다. 더 많으면 나눠 호출하세요.

curl -X POST "https://fplink.net/api/v1/service/messaging/unsubscribes/bulk" \
  -H "X-API-KEY: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel":"SMS","items":[{"value":"01011112222"},{"value":"01033334444"}]}'

{
  "channel": "SMS",
  "accepted": 1,
  "duplicated": 1,
  "invalid": [ { "index": 5, "value": "123", "reason": "PHONE_FORMAT" } ]
}

형식이 틀린 항목이 있어도 나머지는 등록됩니다 — invalid에 그 항목의 위치와 사유가 담깁니다. ?async=true로 호출하면 202와 함께 jobId를 즉시 돌려주고, 진행 상황은 GET /api/v1/service/messaging/contacts/bulk-jobs/{jobId}로 조회합니다.

DELETE /api/v1/service/messaging/unsubscribes

잘못 등록했거나 재동의를 받은 경우의 정정용입니다. id가 아니라 값으로 지웁니다.

curl -X DELETE "https://fplink.net/api/v1/service/messaging/unsubscribes?channel=SMS&value=01012345678" \
  -H "X-API-KEY: YOUR_API_KEY"

DELETE /api/v1/service/messaging/unsubscribes/bulk

curl -X DELETE "https://fplink.net/api/v1/service/messaging/unsubscribes/bulk" \
  -H "X-API-KEY: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"channel":"SMS","values":["01011112222","01033334444"]}'

요청당 최대 1,000건입니다. 응답의 deleted·notFound로 결과를 확인하세요.

GET /api/v1/service/messaging/unsubscribes/check

한 건만 확인합니다. 발송 직전 조회용입니다.

curl "https://fplink.net/api/v1/service/messaging/unsubscribes/check?channel=SMS&value=01012345678" \
  -H "X-API-KEY: YOUR_API_KEY"
# {"channel":"SMS","unsubscribed":true}

웹훅으로 즉시 받기

주기적으로 확인하는 대신, 변경이 생길 때 저희가 알려 드릴 수 있습니다. 콘솔 > 개발자 > 웹훅에서 URL을 등록하고 수신거부 동기화 이벤트를 선택하세요.

{
  "event": "unsubscribe.created",
  "delivery_id": "9f1c…",
  "organization_id": 12,
  "data": {
    "id": 84213,
    "channel": "SMS",
    "phone": "01012345678",
    "method": "080",
    "unsubscribedAt": "2026-09-04T02:11:00Z",
    "cursor": "U01TOjg0MjEz"
  }
}