RedsmsBox

개발자 문서

RESTful 방식의 API로 액세스 토큰을 통해 인증합니다. 요청과 응답은 모두 UTF-8 JSON으로 통일됩니다. 아래 각 엔드포인트에는 바로 실행할 수 있는 curl 예제가 있습니다.

SMS API — 메시지 발송

고객사 업무 시스템에서 직접 발송을 호출할 수 있습니다. to에는 번호 하나를 전달하거나 쉼표로 구분해 일괄 제출할 수 있습니다(1회 최대 1000건). 접수되면 message_id가 반환되며 이를 이용해 도달 상태를 조회할 수 있습니다.

인증 요청 헤더
매개변수
필수
설명
Authorization
예
요청에 API 토큰을 담고 인증 방식을 Bearer로 설정합니다. 예시:Authorization: Bearer {api_token}
Accept
예
application/json으로 설정합니다

메시지 발송

하나 또는 여러 번호로 텍스트 SMS를 발송합니다. 응답의 segments는 이 발송이 차지하는 건수이고 cost는 해당 건의 총 비용입니다.

엔드포인트

POST https://redsmsbox.com/api/v1/sms/send

매개변수

매개변수
필수
유형
설명
to
예
string
수신 번호. E.164 형식(국가 코드 포함). 여러 개일 때는 쉼표로 구분합니다
message
예
string
SMS 본문. 중국 발송은 【발신 명의】본문 형식이며 마케팅 본문은 수신 거부 안내로 끝나야 합니다
channel
아니요
string
회선 ID. 생략하면 계정 기본 회선을 사용합니다
sender_id
아니요
string
국제 SMS의 발신자 식별자(Sender ID)
schedule_at
아니요
string
예약 발송 시각(ISO 8601 UTC). 생략하면 즉시 발송합니다
callback_url
아니요
string
이 메시지의 상태 결과를 받을 Webhook 주소. 계정 기본 설정보다 우선합니다

요청 예시

curl -X POST https://redsmsbox.com/api/v1/sms/send \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{
  "to": "+8613800138000",
  "message": "【RedsmsBox】您的验证码是 123456，5 分钟内有效。"
}'

응답

{
  "ok": true,
  "message_id": "msg_3f7a91",
  "status": "queued",
  "to": "+8613800138000",
  "segments": 1,
  "cost": "0.06",
  "currency": "USD"
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

실패 응답은 항상 이 형식입니다. error 필드는 언제나 영어이며 표시 언어에 따라 바뀌지 않습니다(기계 처리와 로그 집계를 위한 것입니다). error_code로 분기하시고 error의 문구를 대조하지 마십시오. 전체 오류 코드 표는 콘솔의 개발자 문서에 있습니다.

발송 상태 조회

발송 시 반환된 message_id로 개별 메시지의 현재 상태와 통신사 접수 시각을 조회합니다.

엔드포인트

GET https://redsmsbox.com/api/v1/sms/{message_id}

매개변수

매개변수
필수
유형
설명
message_id
예
string
발송 엔드포인트가 반환한 메시지 번호

요청 예시

curl -X GET https://redsmsbox.com/api/v1/sms/msg_3f7a91 \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

응답

{
  "ok": true,
  "message_id": "msg_3f7a91",
  "status": "delivered",
  "to": "+8613800138000",
  "segments": 1,
  "cost": "0.06",
  "currency": "USD",
  "submitted_at": "2026-08-16T09:12:31Z",
  "delivered_at": "2026-08-16T09:12:34Z"
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

실패 응답은 항상 이 형식입니다. error 필드는 언제나 영어이며 표시 언어에 따라 바뀌지 않습니다(기계 처리와 로그 집계를 위한 것입니다). error_code로 분기하시고 error의 문구를 대조하지 마십시오. 전체 오류 코드 표는 콘솔의 개발자 문서에 있습니다.

발송 내역 조회

현재 계정의 발송 내역을 페이지 단위로 조회합니다. 시간과 상태로 필터링할 수 있습니다.

엔드포인트

GET https://redsmsbox.com/api/v1/sms

매개변수

매개변수
필수
유형
설명
status
아니요
string
상태로 필터링합니다. 예: queued / delivered / failed
start
아니요
string
시작 시각(ISO 8601 UTC)
end
아니요
string
종료 시각(ISO 8601 UTC)
page
아니요
number
페이지 번호. 생략하면 1

요청 예시

curl -X GET 'https://redsmsbox.com/api/v1/sms?status=delivered&page=1' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'

응답

{
  "ok": true,
  "page": 1,
  "total": 2,
  "items": [
    {
      "message_id": "msg_3f7a91",
      "status": "delivered",
      "to": "+8613800138000",
      "segments": 1,
      "cost": "0.06"
    }
  ]
}
{
    "ok": false,
    "error_code": "invalid_parameter",
    "error": "The body is not valid JSON, or a field failed validation"
}

실패 응답은 항상 이 형식입니다. error 필드는 언제나 영어이며 표시 언어에 따라 바뀌지 않습니다(기계 처리와 로그 집계를 위한 것입니다). error_code로 분기하시고 error의 문구를 대조하지 마십시오. 전체 오류 코드 표는 콘솔의 개발자 문서에 있습니다.

찾으시는 내용이 없습니까. 언제든 문의해 주십시오

업무 상황을 알려주시면 고객 지원이 발송 가능 범위와 회선 제안, 단가를 안내해 드립니다.

지금 상담하기