시작하기

대량 SMS API 레퍼런스

BulkSMSAPI는 개발자를 위한 대량 SMS API예요. REST로 문자 하나를 보내거나 한 번의 요청으로 최대 10,000개 번호에 배치를 보내 227개 국가에 발송하고, 모든 메시지를 서명된 웹훅으로 추적하며, 미리 충전한 잔액으로 메시지당 비용을 지불할 수 있어요. 이 레퍼런스는 API의 모든 엔드포인트, 필드, 이벤트 및 오류를 다뤄요. 모든 페이지는 Markdown으로도 제공되니, 주소에 .md를 추가해보세요.

기본 URL 및 형식

모든 요청은 HTTPS를 통해 https://bulksmsapi.cc/v1로 전송돼요. 본문은 JSON 형식(Content-Type: application/json, UTF-8)이며, 모든 응답(에러 포함)도 JSON이에요. 시간은 UTC 기준 ISO 8601 형식이고, 금액은 소수점 다섯 자리까지 정확한 미국 달러 문자열("0.00507")로 표시돼요. 따라서 1센트 미만의 가격도 정확하게 표시할 수 있어요.

엔드포인트

메서드 및 경로기능Key
POST /v1/messages단일 번호에 단일 문자 발송Yes
POST /v1/batches최대 10,000개 번호에 단일 문자 또는 번호별 개별 문자 발송Yes
GET /v1/messages/{id}상태 및 가격이 포함된 단일 메시지Yes
GET /v1/messages메시지, 최신순, 배치 또는 상태별 필터링Yes
GET /v1/batches/{id}상태별 개수가 표시된 하나의 배치Yes
GET /v1/batches배치, 최신순Yes
POST /v1/batches/{id}/cancel예약된 배치 취소, 전액 환불Yes
POST /v1/estimates전송 없이 요청 가격 확인Yes
GET /v1/balanceUSD 잔액Yes
GET /v1/pricing모든 국가별 세그먼트 가격No
GET /v1/pricing/{country}특정 국가(ISO 코드)의 가격No

첫 번째 요청

콘솔에서 API 키를 생성하고, 내보낸 다음 메시지를 보내세요. 응답은 202와 함께 메시지 객체가 반환돼요: 비용이 잔액에서 차감되고 메시지가 큐에 들어가요.

curl https://bulksmsapi.cc/v1/messages \
  -H "Authorization: Bearer $BULKSMSAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155550123",
    "text": "Your Northwind code is 482913. It expires in 10 minutes.",
    "reference": "login-7781"
  }'
202 AcceptedJSON
{
  "id": "msg_8F3K2Q9TZ1MX",
  "object": "message",
  "batch_id": "bat_4M7Q1X0PK2RS",
  "to": "+14155550123",
  "country": "US",
  "text": "Your Northwind code is 482913. It expires in 10 minutes.",
  "segments": 1,
  "price": "0.00507",
  "currency": "USD",
  "status": "queued",
  "error": null,
  "reference": "login-7781",
  "created_at": "2026-11-07T09:30:12.418Z",
  "sent_at": null,
  "done_at": null
}

메시지 전송 과정

수신된 메시지는 queued 상태가 돼요 (또는 요청에 send_at이 있으면 scheduled 상태). 큐는 2초마다 메시지를 네트워크로 전달하고, 계정당 분당 최대 1,200개까지 처리해요. 이후 메시지는 sent 상태가 되죠. 최종 상태는 delivered 또는 failed예요; 실패한 메시지는 즉시 잔액으로 환불돼요. 각 최종 상태는 서명된 이벤트와 함께 웹훅을 호출해요.

제한 사항 요약

제한값
API 요청당 수신자 수10,000
콘솔 캠페인당 수신자 수50,000
키당 분당 요청 수600
계정당 분당 네트워크로 전달되는 메시지 수1,200
최대 길이10세그먼트 (1,530 GSM-7 또는 670 UCS-2 문자)
예약 가능 기간2분 후부터 45일 전까지
이벤트당 웹훅 시도 횟수10
Idempotency-Key 유지 기간24시간
계정당 API 키 수10

기계 판독 가능 파일

대량 SMS API 레퍼런스 | BulkSMSAPI 문서