대량 SMS API 레퍼런스

개요

쇼핑몰의 주문 업데이트, 로그인 양식의 코드, 예약 도구의 알림처럼 내 시스템이 메시지를 발생시킬 때 API를 사용하세요. 번호 최대 10,000개를 담은 POST /v1/messages 요청 하나가 캠페인 하나를 만들고, 잔액에서 요금을 차감하고, 모든 메시지를 대기열에 올려요. API로 만든 캠페인도 콘솔에 전송 리포트와 함께 나타나요.

• 모든 금액은 소수점 다섯 자리의 문자열로 된 미국 달러예요. 예: "0.00534".
• 전화번호는 국제 형식이며 앞의 +는 있어도 없어도 돼요. 공백과 하이픈은 제거돼요.
• 시각은 UTC 기준 ISO 8601이에요. 예: 2026-12-01T09:00:00Z.
• 메시지와 캠페인 ID는 MSG-XXXX-XXXX-XXXX, CMP-XXXX-XXXX-XXXX처럼 생겼어요.

인증

콘솔의 API에서 API 키를 만드세요(키는 첫 충전이 반영된 뒤에 열려요). 모든 요청의 Authorization 헤더에 키를 담아 보내세요. 키는 bso_api_ 뒤에 36자가 이어지는 형태이고, 한 번만 표시되니 서버에 비밀 값으로 보관하세요. 새 키를 만들면 이전 키는 즉시 교체돼요.

Authorization: Bearer bso_api_0123456789abcdef0123456789abcdef0123
Content-Type: application/json

한도

메시지 발송

POST/v1/messages

하나 이상의 번호에 문자 하나를 보내요. 전체 비용은 요청이 접수될 때 잔액에서 차감되고, 전송되지 못한 메시지는 이후에 환불돼요. 응답은 상태 201과 모든 메시지가 담긴 캠페인이에요.

curl -X POST https://bulksmsonline.cc/api/v1/messages \
  -H "Authorization: Bearer $BSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":["+447700900412","+33612345678"],"text":"Order 4521 has shipped. Track it at shop.example/t/4521","client_ref":"order-4521"}'

const res = await fetch("https://bulksmsonline.cc/api/v1/messages", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.BSO_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ to: ["+447700900412", "+33612345678"], text: "Order 4521 has shipped.", client_ref: "order-4521" }),
});
if (!res.ok) throw new Error((await res.json()).error.message);
const campaign = await res.json();

import os, requests
res = requests.post("https://bulksmsonline.cc/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['BSO_API_KEY']}"},
    json={"to": ["+447700900412", "+33612345678"], "text": "Order 4521 has shipped.", "client_ref": "order-4521"},
    timeout=30)
res.raise_for_status()
campaign = res.json()

<?php
$ch = curl_init("https://bulksmsonline.cc/api/v1/messages");
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("BSO_API_KEY"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["to" => ["+447700900412", "+33612345678"], "text" => "Order 4521 has shipped.", "client_ref" => "order-4521"])]);
$campaign = json_decode(curl_exec($ch), true);

HTTP/1.1 201 Created
{
  "id": "CMP-7KQ2-M9XA-4HTD",
  "status": "sending",
  "channel": "api",
  "recipients": 2,
  "segments": 1,
  "encoding": "GSM-7",
  "cost": "0.02158",
  "refunded": "0.00000",
  "client_ref": "order-4521",
  "send_at": null,
  "counts": { "queued": 2, "submitted": 0, "delivered": 0, "failed": 0, "canceled": 0 },
  "skipped": [],
  "balance": "118.43120",
  "messages": [
    { "id": "MSG-3RTW-81KD-ZQ0P", "to": "+447700900412", "country": "GB", "segments": 1, "price": "0.00834", "status": "queued" },
    { "id": "MSG-5HNA-4C2E-7YVB", "to": "+33612345678", "country": "FR", "segments": 1, "price": "0.01324", "status": "queued" }
  ]
}

발송 견적

POST/v1/quote

/v1/messages와 같은 본문을 받아서, 발송하거나 비용을 차감하지 않고 정확한 비용, 세그먼트, 인코딩을 돌려줘요. 사용자가 확정하기 전에 직접 만든 화면에서 요금을 보여줄 때 사용하세요.

{
  "recipients": 2,
  "skipped": [],
  "segments": 1,
  "encoding": "GSM-7",
  "cost": "0.02158",
  "balance": "118.45278",
  "countries": [ { "country": "GB", "recipients": 1, "cost": "0.00834" }, { "country": "FR", "recipients": 1, "cost": "0.01324" } ]
}

잔액

GET/v1/balance

{ "balance": "118.43120", "currency": "USD" }

요금

GET/v1/rates

GET/v1/rates/{country}

모든 국가 또는 두 글자 ISO 국가 코드 하나에 대한 SMS 세그먼트 1건의 요금이에요. 이 두 엔드포인트는 공개되어 있어서 키가 필요 없어요.

{ "country": "DE", "name": "Germany", "calling_code": "+49", "price": "0.01544", "currency": "USD", "per": "segment" }

메시지 상태

GET/v1/messages/{id}

{
  "id": "MSG-3RTW-81KD-ZQ0P",
  "campaign_id": "CMP-7KQ2-M9XA-4HTD",
  "to": "+447700900412",
  "country": "GB",
  "segments": 1,
  "price": "0.00834",
  "status": "delivered",
  "error": null,
  "created_at": "2026-11-07T09:00:02Z",
  "submitted_at": "2026-11-07T09:00:03Z",
  "final_at": "2026-11-07T09:00:08Z"
}

캠페인

GET/v1/campaigns/{id}

GET/v1/campaigns/{id}/messages?offset=0&limit=100

첫 번째는 상태별 건수가 담긴 캠페인을 돌려주고, 두 번째는 해당 캠페인의 메시지를 페이지당 최대 1,000건씩 보여줘요. 콘솔에서 보낸 캠페인도 페이지에 표시된 ID로 같은 방식으로 조회할 수 있어요.

예약 발송 취소

POST/v1/campaigns/{id}/cancel

send_at으로 만들어졌고 아직 시작하지 않은 캠페인을 중지해요. 모든 메시지가 취소되고 비용 전액이 잔액으로 돌아와요. 이미 발송 중인 캠페인은 409 not_scheduled로 응답해요.

전송 웹훅

콘솔의 API에서 HTTPS URL을 추가하면 각 최종 상태(delivered 또는 failed)가 POST 요청으로 전달돼요. 8초 안에 아무 2xx 상태로 응답하세요. 그 밖의 응답과 시간 초과는 20초, 1분, 5분, 15분 뒤에, 이어서 1시간, 3시간, 6시간, 12시간 뒤에 다시 시도하며 총 9번이에요. 같은 이벤트가 두 번 도착할 수 있으니 event_id로 한 번만 처리하세요.

POST https://your-server.example/sms-status
Content-Type: application/json
X-BulkSMSOnline-Signature: t=1794042008,v1=5f0c2a...e91b

{
  "type": "message.status",
  "event_id": "ev_8f1c22d0a4b97e63c1f0",
  "sent_at": "2026-11-07T09:00:09Z",
  "data": {
    "message_id": "MSG-3RTW-81KD-ZQ0P",
    "campaign_id": "CMP-7KQ2-M9XA-4HTD",
    "to": "+447700900412",
    "country": "GB",
    "status": "delivered",
    "error": null,
    "segments": 1,
    "price": "0.00834",
    "currency": "USD",
    "client_ref": "order-4521",
    "final_at": "2026-11-07T09:00:08Z"
  }
}

서명 검증

헤더에는 Unix 시각 t와 서명 v1이 담겨 있어요. v1은 웹훅 시크릿으로 문자열 "t.raw_body"에 HMAC-SHA256을 계산한 hex 값이에요. JSON을 파싱하기 전에 원본 본문으로 계산하고, 일정한 시간으로 비교하고, 5분보다 오래된 이벤트는 거부하세요.

import crypto from "node:crypto";

export function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || "");
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(m[1] + "." + rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}

import hmac, hashlib, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", header or "")
    if not m or abs(time.time() - int(m.group(1))) > 300:
        return False
    want = hmac.new(secret.encode(), m.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, m.group(2))

<?php
function verify(string $raw, string $header, string $secret): bool {
  if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)) return false;
  if (abs(time() - (int)$m[1]) > 300) return false;
  $want = hash_hmac('sha256', $m[1] . '.' . $raw, $secret);
  return hash_equals($want, $m[2]);
}

상태

캠페인 상태는 scheduled, sending, complete, canceled 중 하나예요.

오류

오류는 HTTP 상태와 JSON 본문으로 응답해요: { "error": { "code": "insufficient_balance", "message": "..." } }. 요청이 오류로 응답되면 요금은 부과되지 않아요.