발송

POST /v1/messages로 SMS 보내기

POST/v1/messages

하나의 번호에 문자를 보내요. 요청이 수락되면 잔액에서 비용이 차감돼요.

요청 본문

  • tostring필수

    국제 형식의 번호예요 (예: +14155550123). 공백, 대시, 괄호, 00 접두사는 자동으로 제거돼요.

  • textstring필수

    메시지 내용이에요. 최대 10세그먼트까지 가능해요. '텍스트와 세그먼트'를 참고하세요.

  • referencestring선택

    최대 100자까지 지정할 수 있는 고유 ID예요. 메시지 객체와 모든 웹훅에 포함돼요.

  • send_atstring선택

    발송 예약 시간이에요 (ISO 8601 형식, 2분 후부터 45일 이내). 지정하지 않으면 즉시 전송 대기열에 들어가요.

재시도를 안전하게 하려면 Idempotency-Key 헤더를 추가하세요. 멱등성 문서를 참고하세요.

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
}

메시지 객체

필드

  • idstring

    메시지 ID (msg_ 뒤에 12자리 문자).

  • objectstring

    항상 message.

  • batch_idstring

    메시지가 속한 배치 ID (단일 메시지도 배치가 생성돼요).

  • tostring

    정제된 E.164 형식의 번호예요.

  • countrystring

    번호가 적용된 국가의 ISO 3166 코드예요.

  • textstring

    전송된 실제 메시지 내용 (병합 필드가 채워진 상태).

  • segmentsinteger

    메시지가 사용한 SMS 세그먼트 수예요.

  • pricestring

    이 메시지의 비용이에요 (USD, 소수점 5자리, 세그먼트당 가격 × 세그먼트 수).

  • currencystring

    항상 USD.

  • statusstring

    scheduled, queued, sent, delivered, failed 또는 canceled.

  • errorobject or null

    실패 또는 취소된 메시지의 오류 코드와 설명이에요.

  • referencestring or null

    요청 시 지정한 고유 참조 값이에요.

  • created_atstring

    요청이 수락된 시간이에요 (ISO 8601, UTC).

  • sent_atstring or null

    메시지가 네트워크로 전달된 시간이에요.

  • done_atstring or null

    최종 상태(delivered, failed 또는 canceled)가 설정된 시간이에요.

메시지 조회

GET/v1/messages/{id}

msg_ ID로 특정 메시지를 조회해요. 다른 계정의 메시지는 404 오류가 반환돼요.

curl https://bulksmsapi.cc/v1/messages/msg_8F3K2Q9TZ1MX \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"

메시지 목록

GET/v1/messages

계정의 메시지예요, 최신 순으로 정렬돼요.

쿼리 매개변수

  • batch_idstring선택

    이 bat_ 배치의 메시지만 있어요.

  • statusstring선택

    scheduled, queued, sent, delivered, failed 또는 canceled.

  • limitinteger선택

    1부터 100까지, 기본값 20.

  • starting_afterstring선택

    msg_ id를 기준으로 페이지가 시작해요. 이전 페이지의 마지막 id를 사용하세요.

curl "https://bulksmsapi.cc/v1/messages?status=failed&limit=50" \
  -H "Authorization: Bearer $BULKSMSAPI_KEY"
200 OKJSON
{
  "object": "list",
  "data": [ { "id": "msg_8F3K2Q9TZ1MX", "object": "message", "status": "failed", "...": "..." } ],
  "has_more": false
}
POST /v1/messages로 SMS 보내기 | BulkSMSAPI 문서