발송 제외 목록

알림톡을 보내지 않을 번호를 등록·조회·해제합니다. 서버가 발송 직전에 이 목록과 대조해서, 단건 발송은 3021 로 거부되고 벌크 발송에서는 skipped 로 빠지며 과금되지 않습니다.

고객이 스스로 등록하는 경로는 없습니다

템플릿이 사전심사를 거치므로 발송 시점에 수신거부 링크나 버튼을 끼워 넣을 수 없습니다. 수신자 쪽 거부는 카카오톡 채널 차단으로 갈음합니다.

이 목록에 쌓이는 것은 가맹점이 이 API 나 관리자 화면으로 직접 넣은 번호뿐입니다.

엔드포인트 이름은 optouts 입니다. 화면 용어와 경로가 다릅니다.

1목록 조회

GEThttps://message.bootapi.com/alimtalk/optoutsBasic Auth

요청 파라미터

파라미터 타입 필수 설명
phone String 선택 번호 필터. 숫자만 남겨 부분일치​​로 찾습니다
page Integer 선택 페이지 번호 (기본 1). 50건 단위

코드 예제

curl -X GET "https://message.bootapi.com/alimtalk/optouts?page=1" \
  -H "Authorization: Basic {base64(client_key:secret_key)}"bash

응답

{
  "list": [
    {
      "id": "68b0f2a1c3d4e5f6a7b8c9f0",
      "phone": "01012345678",
      "scope": 2,
      "global": false,
      "releasable": true,
      "source": 2,
      "reason": "고객 요청",
      "opted_out_at": "2026-08-27 09:00:00 +0900",
      "created_at": "2026-08-27 09:00:00 +0900"
    }
  ],
  "count": 1,
  "page": 1
}json
필드 설명
scope 2 프로젝트. 현재 만들어지는 값은 이것뿐입니다
source 등록 경로. 2 API · 3 관리자 화면
reason 등록할 때 남긴 메모
global · releasable 부트페이 전역 차단용으로 남아 있는 필드입니다. 전역 차단을 만드는 경로가 없어 global 은 false, releasable 은 true 로 옵니다

시각 필드 형식은 응답의 시각 형식을 참고합니다.

2등록

같은 번호를 다시 등록해도 멱등입니다. 기존 레코드를 그대로 돌려줍니다.

POSThttps://message.bootapi.com/alimtalk/optoutsBasic Auth

요청 파라미터

파라미터 타입 필수 설명
phone String 필수 제외할 번호 (하이픈 무관)
reason String 선택 사유 메모

코드 예제

curl -X POST "https://message.bootapi.com/alimtalk/optouts" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "01012345678",
    "reason": "고객 요청"
  }'bash

응답

등록된 항목을 돌려줍니다. 구조는 목록 항목과 같습니다.

등록 이벤트를 서버로 받으려면 웹훅에서 320 을 구독합니다. 기본은 미구독입니다.

3발송 전 확인

발송 판정과 같은 기준​​으로 대조합니다. 발송 시 3021 이나 skipped 가 될 번호를 미리 걸러낼 수 있습니다.

POSThttps://message.bootapi.com/alimtalk/optouts/checkBasic Auth

요청 파라미터

단건(phone)과 다건(phones) 둘 다 받습니다.

파라미터 타입 필수 설명
phones Array 선택 확인할 번호 배열. 1회 최대 1,000건​, 중복은 서버가 제거합니다
phone String 선택 단건 확인용 (phones 를 안 줄 때)

둘 다 비어 있거나 1,000건을 넘으면 -48 로 거부됩니다.

코드 예제

curl -X POST "https://message.bootapi.com/alimtalk/optouts/check" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "phones": ["01012345678", "01087654321"]
  }'bash

응답

{
  "list": [
    {
      "phone": "01012345678",
      "opted_out": true,
      "global": false,
      "releasable": true,
      "opted_out_at": "2026-08-27 09:00:00 +0900"
    },
    {
      "phone": "01087654321",
      "opted_out": false,
      "global": false,
      "releasable": false,
      "opted_out_at": null
    }
  ],
  "count": 2,
  "opted_out_count": 1
}json
필드 설명
opted_out true 면 발송이 막힙니다
count 중복을 제거한 조회 번호 수
opted_out_count 그중 제외 상태인 건수

4해제

없는 번호를 해제해도 성공으로 처리되는 멱등 동작입니다.

DELETEhttps://message.bootapi.com/alimtalk/optouts/{phone}Basic Auth

요청 파라미터

파라미터 타입 필수 설명
phone String 필수 해제할 번호 (경로 파라미터). id 가 아니라 전화번호​​입니다

코드 예제

curl -X DELETE "https://message.bootapi.com/alimtalk/optouts/01012345678" \
  -H "Authorization: Basic {base64(client_key:secret_key)}"bash

응답

{
  "phone": "01012345678",
  "released": true,
  "global_blocked": false
}json
필드 설명
released 실제로 지운 레코드가 있었는지. 원래 없었으면 false 지만 오류는 아닙니다
global_blocked 전역 차단용 필드입니다. 전역 차단을 만드는 경로가 없어 false 로 옵니다

에러 코드

코드 error_code 메시지 대처 방법
-48 INVALID_PARAMETER 번호 형식 오류, 번호 없음, 상한 초과 숫자가 포함된 유효한 번호인지 확인하고, 확인 요청은 1,000건 이하로 나눠 보냅니다

함께 보기