API 문서
엔드포인트는 https://portsms.com/api/v1. 모든 응답은 JSON.
인증
모든 요청에 Authorization: Bearer <token> 헤더를 포함합니다. 토큰은 가입시 1회 발급. 분실하면 복구 불가.
Authorization: Bearer tok_01HJZABCDE2YS83F0GQV9JXM1R
POST /send
단일 혹은 여러 수신번호로 메시지 발송. 1건 요청에 최대 1,000 수신자.
POST /api/v1/send
Content-Type: application/json
{
"to": ["+14155550123", "+447700900123"],
"from": "PortSMS",
"text": "코드: 739215"
}응답
{
"id": "msg_01HJZ27YVM3QX0WK6PCB4F1R9A",
"accepted": 2,
"rejected": 0,
"cost_usd": "0.0177",
"status_url": "/api/v1/status/msg_01HJZ27YVM3QX0WK6PCB4F1R9A"
}GET /status/:id
발송 단일 ID의 수신자별 상태.
GET /api/v1/status/msg_01HJZ...
{
"id": "msg_01HJZ...",
"created_at": "2026-10-12T20:30:14Z",
"parts": 1,
"cost_usd": "0.0177",
"recipients": [
{ "to": "+14155550123", "status": "delivered", "ms_to_deliver": 842 },
{ "to": "+447700900123", "status": "delivering" }
]
}GET /balance
현재 토큰의 잔액 (USD).
GET /api/v1/balance
{ "balance_usd": "412.85", "credit_usd": "412.85" }Webhook
가입시 지정한 URL로 발송 상태 변경을 푸시. X-PortSMS-Signature: t=<ts>,v1=<hex> 헤더로 HMAC-SHA256 서명 (timestamp.body).
POST https://your-site.com/webhook
X-PortSMS-Signature: t=1697083214,v1=4a9b2c...
{
"event": "message.delivered",
"id": "msg_01HJZ...",
"recipient": "+14155550123",
"ms_to_deliver": 842,
"at": "2026-10-12T20:30:16Z"
}이벤트: message.sent, message.delivered, message.failed, balance.low. 재시도 8회 (지수 백오프).
오류 코드
401 unauthorized| 토큰 누락 또는 폐기됨402 insufficient_credit| 크레딧 부족400 bad_request| 번호/문구 형식 오류429 rate_limited| 분당 300회 초과 (Retry-After 헤더 참조)502 route_down| 해당 국가 라우트 일시 불가 (자동 재시도)
제한
- 분당 300회 요청 (/send)
- 요청당 수신자 최대 1,000
- 문구 최대 10 parts (1,530자)
- 토큰 1개당 하루 50만 건 (초과시 수동 승인)