Skip to main content
POST

Authorizations

​
Authorization
string
header
required

워크스페이스 API 키를 Authorization: Bearer <token> 형식으로 보냅니다.

Headers

​
Idempotency-Key
string | null

같은 POST 요청을 24시간 동안 안전하게 재시도하기 위한 선택적 멱등성 키입니다. 지정할 경우 비어 있으면 안 되며 최대 255자까지 허용합니다.

Body

application/json

대량 문자 발신 생성 요청 본문입니다. items에는 수신자가 들어가며, scheduled_at과 send_time_window를 모두 만족해야 메시지를 발신합니다.

POST /v3/sms-batches 요청 본문입니다.

​
name
string
required

대량 문자 발신 이름입니다. 앞뒤 공백을 지운 뒤 1~255자여야 하며 공백만으로는 만들 수 없습니다.

Required string length: 1 - 255
Example:

"5월 공지 발신"

​
from_number
string
required

대량 문자 발신 전체가 공유하는 발신번호입니다. 인증된 워크스페이스가 소유하고 문자 발신이 켜진 번호여야 합니다.

Example:

"07011112222"

​
items
SMSBatchItem · object[]
required

문자를 받을 수신 항목 목록입니다(1건 이상). 요청당 최대 3000건까지 담을 수 있고, 워크스페이스당 분당 최대 6000건까지 등록할 수 있습니다. 한도를 넘으면 RATE_LIMIT_EXCEEDED(429)로 거절됩니다.

Required array length: 1 - 3000 elements
​
scheduled_at
integer | null

예약 실행 시각입니다. unix milliseconds 형식입니다.

​
send_time_window
SMSBatchSendTimeWindow · object | null

발신 허용 시간대입니다. 생략하면 24시간 매일 발신할 수 있습니다. 허용 시간대 밖이면 발신을 멈추고, auto_resume이 true이면 다음 허용 시간대에 이어서 발신합니다.

​
reseller_code
string | null

특수유형 부가통신사업자 식별코드입니다(숫자 9자리). 문자중계·재판매사업자가 아니면 생략합니다. 허용된 워크스페이스에서만 전송됩니다.

Pattern: ^\d{9}$

Response

성공 응답

대량 문자 발신 한 건입니다. 문자별 결과는 GET /v3/sms?batch_id= 로 조회합니다.

​
id
string
required

대량 문자 발신의 고유 식별자입니다(UUID).

​
name
string | null
required

대량 문자 발신 이름입니다. 이름 없이 만든 이전 대량 문자 발신은 null입니다.

​
status
enum<string>
required

대량 문자 발신 상태입니다. canceled는 취소됨, paused는 일시정지 중, draft는 예약 시각 전의 대기 상태입니다. 그 외에는 pending(발신 전), ongoing(발신 중이거나 발신이 끝난 뒤 통신사 결과를 기다리는 중), success(모든 결과가 정해졌거나 마지막 발신 후 10분이 지나 끝남, 실패·차단 항목이 있을 수 있음), fail(접수된 항목 없이 끝남)입니다.

Available options:
draft,
pending,
ongoing,
paused,
success,
fail,
canceled
​
from_number
string
required

대량 문자 발신 전체가 공유하는 발신번호입니다.

​
total_count
integer
required

이 대량 문자 발신에 담은 전체 문자 수입니다.

Required range: x >= 0
​
success_count
integer
required

요금이 부과되는 성공(sent) 항목 수입니다.

Required range: x >= 0
​
failure_count
integer
required

발신에 실패한(failed) 항목 수입니다.

Required range: x >= 0
​
pending_count
integer
required

아직 결과가 정해지지 않은 문자 수입니다. 발신하지 않은 pending 문자와 통신사의 최종 결과를 기다리는 queued 문자를 합한 값이며, success_count + failure_count + pending_count + blocked_count + canceled_count가 total_count와 같습니다. 문자별 결과는 GET /v3/sms?batch_id= 로 조회합니다.

Required range: x >= 0
​
blocked_count
integer
required

제한된 내용이 포함되어 발신하지 않은(blocked) 항목 수입니다.

Required range: x >= 0
​
canceled_count
integer
required

대량 문자 발신 취소로 발신하지 않은(canceled) 항목 수입니다.

Required range: x >= 0
​
send_time_window
SMSBatchSendTimeWindow · object | null
required

발신 허용 시간대입니다. 시간대를 정하지 않고 만든 이전 대량 문자 발신은 null입니다.

​
scheduled_at
integer | null
required

예약 실행 시각입니다. unix milliseconds 형식입니다.

​
paused_at
integer | null
required

일시정지한 시각입니다(unix ms). 일시정지 중이 아니면 null입니다.

​
canceled_at
integer | null
required

취소한 시각입니다(unix ms). 취소하지 않았으면 null입니다.

​
created_at
integer
required

리소스 생성 시각입니다. unix milliseconds 형식입니다.

​
finished_at
integer | null
required

대량 문자 발신이 끝난 시각입니다(unix ms). 끝나지 않았으면 null입니다.

​
sheet_id
string | null
required

대량 문자 발신 생성에 사용한 시트 식별자입니다. 시트를 거치지 않았으면 null입니다.