SMS · LMS · MMS 발송

단문(SMS)·장문(LMS)·포토(MMS) 문자를 발송합니다. 채널은 URL 경로로 구분합니다. 같은 문구를 여러 명에게 보내거나, 수신자마다 다른 문구를 보낼 수 있습니다.

POST /v1/messages/sms

POST /v1/messages/lms

POST /v1/messages/mms

요청 본문

필드	타입	설명
`from` 필수	string	발신번호. 승인되고 API 허용된 번호여야 합니다.
`to` / `recipients` 택1	string[] / object[]	수신자. `to` 는 번호 문자열 배열(동일 문구), `recipients` 는 수신자별 문구·참조키를 지정합니다. 동일 문구·SMS 개별 문구 최대 1,000명, LMS/MMS 개별 문구 최대 500명. (한도)
`text`	string	본문. `recipients[].text` 가 있으면 그 수신자는 개별 문구를 사용합니다. (MMS 는 비워도 됨)
`subject`	string	LMS 제목 (LMS 필수, 30자 이하). MMS 에서는 선택.
`file_ids`	int[]	MMS 이미지 ID 1~3개. 이미지 업로드로 먼저 발급받습니다. (MMS 필수)
`send_at`	string	예약 발송 시각. ISO 8601 (예: `2026-11-07T09:00:00+09:00`). 오프셋이 없으면 KST. 생략하면 즉시 발송. 현재 ~ 180일 이내.
`ad`	boolean	광고성 문자 여부 (기본 `false`). `true` 이면 본문 앞에 `(광고)`, 뒤에 `무료수신거부 080…` 이 자동으로 붙습니다.
`exclude_optout`	boolean	080 수신거부 번호 자동 제외 (기본 `true`)
`name`	string	발송 이름(관리용, 200자 이하). 생략하면 자동 생성.
`client_ref`	string	고객사 요청 참조키 (1~64자). 자세히
`dry_run`	boolean	`true` 이면 검증·금액 계산만 하고 발송하지 않음 (`200`)

recipients 항목

필드	설명
`to` 필수	수신번호
`text`	이 수신자 전용 문구 (생략 시 최상위 `text`)
`ref`	수신자별 참조키 (1~64자). 결과 조회·Webhook 의 `client_ref` 로 돌아옵니다.

채널별 한도

채널	본문	제목	비고
SMS	90 byte 이하 (한글 2byte, 영문·숫자 1byte)	없음	초과 시 `422 MESSAGE_TOO_LONG` — LMS 로 보내세요
LMS	2,000자 이하	30자 이하 (필수)
MMS	2,000자 이하	선택	이미지 1~3장 필수

웹 화면과 달리 API 는 한도를 넘는 본문을 조용히 잘라 보내지 않고 오류로 알려 드립니다. ad: true 일 때는 자동으로 붙는 광고 문구도 길이에 포함됩니다.

예시

같은 문구를 여러 명에게

curl

curl -X POST https://api-01.redbean8.io.kr/v1/messages/sms \
  -H "Authorization: Bearer $REDBEAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: notice-20261107-01" \
  -d '{
    "from": "0212345678",
    "to": ["01011112222", "01033334444"],
    "text": "[레드빈8] 11/7 정기점검 안내",
    "client_ref": "notice-20261107-01"
  }'

수신자마다 다른 문구 + 예약 발송

JSON

{
  "from": "0212345678",
  "send_at": "2026-11-07T09:00:00+09:00",
  "recipients": [
    { "to": "01011112222", "text": "홍길동님, 주문(A-1001)이 출고되었습니다.", "ref": "A-1001" },
    { "to": "01033334444", "text": "김영희님, 주문(A-1002)이 출고되었습니다.", "ref": "A-1002" }
  ],
  "client_ref": "ship-20261107-am"
}

LMS

JSON

{
  "from": "0212345678",
  "to": ["01011112222"],
  "subject": "11월 이용 안내",
  "text": "안녕하세요. 90byte 를 넘는 긴 안내 문구는 LMS 로 발송합니다. ……",
  "ad": false
}

MMS (이미지 첨부)

JSON

{
  "from": "0212345678",
  "to": ["01011112222"],
  "subject": "신상품 안내",
  "text": "이번 주 신상품을 소개합니다.",
  "file_ids": [101, 102]
}

응답

정상 접수 시 202 Accepted.

JSON

{
  "request_id": "req_a2b3c74d17246af7aa5f",
  "data": {
    "message_id": 1374,
    "channel": "sms",
    "status": "SCHEDULED",
    "accepted": 1,
    "rejected_count": 1,
    "rejected": [
      { "index": 1, "to": "0101234", "reason": "INVALID_NUMBER" }
    ],
    "amount": 10.5,
    "send_at": "2026-11-07T09:00:00+09:00",
    "client_ref": "ship-20261107-am"
  }
}

필드	설명
`message_id`	발송 건 ID. 조회·취소에 사용합니다.
`status`	`ACCEPTED`(즉시) 또는 `SCHEDULED`(예약)
`accepted`	접수된 수신자 수 (요금이 차감된 건수)
`rejected[]`	접수되지 않은 수신자와 사유 (최대 100건 표시, 전체 건수는 `rejected_count`)
`amount`	차감된 금액(원)

부분 접수 — rejected 사유

수신자 중 일부만 문제가 있으면 정상 번호만 접수하고 나머지는 rejected 로 알려 드립니다. 접수 가능한 수신자가 0명이면 422 INVALID_REQUEST 입니다.

reason	의미
`INVALID_NUMBER`	휴대전화 번호 형식이 아님
`DUPLICATE`	같은 요청 안에서 번호 중복 (첫 번째만 접수)
`OPTED_OUT`	080 수신거부 등록 번호 (`exclude_optout: true` 일 때)

자주 만나는 오류

HTTP	code	조치
402	`INSUFFICIENT_BALANCE`	잔액 충전 후 재시도
403	`SENDER_API_NOT_ENABLED`	발신번호 관리에서 API 허용 켜기
422	`SENDER_NOT_APPROVED`	승인된 발신번호 사용
422	`MESSAGE_TOO_LONG`	본문 단축 또는 LMS 사용
422	`INVALID_SEND_AT`	예약 시각 형식·범위 확인
422	`FILE_NOT_FOUND`	MMS 이미지가 없거나 만료됨 — 다시 업로드

전체 목록은 오류 코드를 참고하세요.