한 요청으로 같은 템플릿을 여러 수신자에게 보냅니다. 수신자별로 변수와 ref_id 를 따로 줄 수 있습니다.
100명을 넣으면 100건이 나갑니다. 테스트할 때 목록을 그대로 넣지 않도록 주의합니다.
실패 처리 규칙
| 상황 | 동작 |
|---|---|
| 쿼터 초과 | 요청 시점에 전체 거부 (3022). 일부만 나가지 않습니다. 한도는 recipients 길이 전체로 셉니다 — 제외 목록으로 건너뛸 건·이미 접수된 ref_id 도 포함됩니다. 새 프로젝트는 분당 10건이 상한이라 11명부터 거부됩니다(개요) |
| 개별 수신자 변수 누락·번호 오류 | 그 건만 rejected, 나머지는 정상 발송 |
| 발송 제외 목록에 있는 번호 | 그 건은 skipped. 과금되지 않고 발송 기록도 만들지 않습니다 |
요청 파라미터
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
template_code |
String | 필수 | 템플릿 코드 |
recipients |
Array | 필수 | 수신자 배열 (최소 1건) |
└─ to |
String | 필수 | 수신번호 |
└─ variables |
Object | 선택 | 이 수신자의 변수 치환값 |
└─ ref_id |
String | 선택 | 이 수신자의 멱등 키 |
reserved_at |
String | 선택 | 예약 발송 시각 (ISO8601) |
sender_key |
String | 선택 | 발신 채널 senderKey |
user_id |
String | 선택 | 가맹점 회원 식별자 (기록용) |
webhook_url |
String | 선택 | 이 요청으로 나간 모든 건의 결과 웹훅을 받을 주소 (https:// 만, 2,000자 이하) |
수신자마다 따로 정할 수는 없고, 이 요청으로 나간 모든 수신자 건의 결과 웹훅이 같은 주소로 갑니다. 형식이 틀리면 한 건도 나가지 않고 요청 전체가 3028 로 거부됩니다. 자세한 규칙은 단건 발송과 같습니다.
현재 reserved_at 이 날짜로 해석되지 않거나 과거 시각이면 오류 없이 모든 수신자에게 바로 보냅니다(과금 포함). 예약할 때는 2026-08-27T10:00:00+09:00 처럼 오프셋까지 붙인 ISO8601 로 보내고, 응답의 receipt_id 로 발송 결과 조회를 호출해 reserved_at 이 채워졌는지 확인합니다.
쿼리스트링으로 보낸 JSON 문자열도 받지만 URL 길이 제한이 있습니다.
코드 예제
curl -X POST "https://message.bootapi.com/alimtalk/send/bulk" \
-H "Authorization: Basic {base64(client_key:secret_key)}" \
-H "Content-Type: application/json" \
-d '{
"template_code": "G_RESTOCK_NOTICE_user",
"recipients": [
{
"to": "01012345678",
"ref_id": "bulk-0001",
"variables": { "company_name": "부트페이몰", "user_name": "홍길동" }
},
{
"to": "01087654321",
"ref_id": "bulk-0002",
"variables": { "company_name": "부트페이몰", "user_name": "김철수" }
}
]
}'bashrequire 'bootpay'
commerce = BootpayStore::RestClient.new(client_key: 'your-commerce-client-key', secret_key: 'your-commerce-secret-key')
response = commerce.alimtalk_send_bulk(
template_code: 'G_RESTOCK_NOTICE_user',
recipients: [
{ to: '01012345678', ref_id: 'bulk-0001', variables: { company_name: '부트페이몰', user_name: '홍길동' } },
{ to: '01087654321', ref_id: 'bulk-0002', variables: { company_name: '부트페이몰', user_name: '김철수' } }
]
)
puts response.dataruby응답
{
"count": 2,
"requested": 2,
"skipped": 0,
"rejected": 0,
"receipts": [
{
"receipt_id": "68b0f2a1c3d4e5f6a7b8c9d0",
"ref_id": "bulk-0001",
"to": "01012345678",
"status": "requested"
},
{
"receipt_id": "68b0f2a1c3d4e5f6a7b8c9d1",
"ref_id": "bulk-0002",
"to": "01087654321",
"status": "requested"
}
]
}json| 필드 | 설명 |
|---|---|
| count | 요청한 수신자 수 |
| requested | 접수에 성공한 건수 |
| skipped | 발송 제외 목록에 걸려 건너뛴 건수 |
| rejected | 건별로 거부된 건수 |
같은 ref_id 로 이미 접수된 건은 기존 결과를 그대로 돌려주므로 status 가 success·canceled 일 수 있습니다. 이런 건은 receipts 에만 있고 requested·skipped·rejected 어디에도 세지 않으므로, 세 값의 합이 count 보다 작을 수 있습니다.
거부·건너뜀 항목에는 사유 code 가 함께 들어옵니다. 에러 응답의 error_code 와 달리 이 code 는 숫자입니다.
{
"to": "01099998888",
"status": "skipped",
"code": 3021
}json발송 전 제외 번호 확인
발송 전 확인으로 제외 번호를 미리 걸러낼 수 있습니다. 한 번에 최대 1,000건까지 확인할 수 있습니다.
에러 코드
| 코드 | error_code | 메시지 | 대처 방법 |
|---|---|---|---|
-48 |
INVALID_PARAMETER |
recipients 형식 오류 | JSON 배열로 보냈는지, to 가 있는지 확인합니다 |
3022 |
RATE_LIMIT_EXCEEDED |
발송 한도 초과 | 요청 전체가 거부됩니다. 건수를 나눠 보냅니다 |
3028 |
WEBHOOK_URL_INVALID |
웹훅 주소 형식 오류 | 요청 전체가 거부됩니다. webhook_url 은 https:// 로 시작하고 2,000자 이하여야 합니다 |
11101 |
MESSAGE_PREPAID_NOT_CHARGED |
선불 첫 충전 전 | 요청 전체가 거부됩니다. 첫 충전을 마친 뒤 보냅니다 |
16312 |
SERVICE_CHARGE_BALANCE_INSUFFICIENT |
선불 잔액 부족 | 잔액이 모자란 건만 rejected 로 빠지고 code 에 담깁니다. 충전 후 그 건만 다시 보냅니다 |
16315 |
MESSAGE_BILLING_PAYER_NOT_PREPAID |
이용료를 내는 리셀러가 선불 요금제가 아님 | 요청 전체가 거부됩니다. 리셀러에게 문의합니다 |
그 밖의 게이트 오류와 리셀러가 이용료를 대신 낼 때의 판정 기준은 단건 발송과 같습니다.



