개발자를 위한 SMS8 API.
SMS8 API로 SMS와 MMS를 보내면 고객님의 휴대폰에서 발송됩니다. 모든 엔드포인트에 API 키 하나, 답장과 전송 보고서용 웹훅, Node용 SDK, 바로 쓰는 PHP 및 C# 클래스, AI 에이전트용 MCP 서버를 제공합니다.

npm install sms8-sdkclaude mcp add --transport http sms8 https://mcp.sms8.ioSMS8_API_KEY=your_api_key npx -y sms8-sdk mcphttps://mcp.sms8.ioClaude Desktop: 설정, 커넥터, 사용자 지정 커넥터 추가
API 작동 방식
모든 요청은 app.sms8.io로 갑니다. API 키와 필요한 필드를 담아 간단한 폼 POST를 보내세요. 명확한 성공 플래그와 메시지 정보가 담긴 JSON이 돌아옵니다.
그 뒤에서 메시지는 페어링하신 안드로이드 폰으로 전달되고, 그 휴대폰이 자기 SIM으로 발송합니다. 답장과 전송 보고서도 같은 방식으로 돌아옵니다.
API에는 인위적인 속도 제한이 없습니다. 실제 처리량은 SIM에 달려 있습니다. 더 보내려면 휴대폰을 추가하시거나 듀얼 SIM 휴대폰을 쓰세요.
할 수 있는 일
작업마다 엔드포인트 하나입니다. 전체 참조 문서에 모든 필드가 나와 있습니다.
SMS와 MMS 발송
메시지 한 건, 여러 사람에게 일괄 발송, 저장된 연락처 목록에 단체 발송을 할 수 있습니다. MMS에는 이미지 링크를 추가하세요. 나중으로 예약하거나 우선 발송으로 설정할 수 있습니다.
발신자 선택
휴대폰과 SIM 하나로 보내거나, 모든 휴대폰을 번갈아 쓰거나, 부하를 나누도록 메시지마다 무작위로 고르세요.
조회와 재발송
ID로 메시지를 조회해 상태를 확인하세요. 실패한 메시지는 호출 한 번으로 대기열에 다시 넣습니다.
OTP 인증번호
일회용 인증번호를 보내고 사용자가 입력한 값을 확인합니다. 수신자를 보호하기 위해 인증번호는 전화번호당 하루 발송 수가 제한됩니다.
기기와 연락처
페어링된 휴대폰과 SIM 목록을 확인하세요. 이름, 태그, 사용자 정의 필드로 연락처를 만들거나 업데이트합니다.
USSD
잔액 조회 같은 통신사 USSD 코드를 페어링된 휴대폰에서 보내고 응답을 읽습니다.
인증과 응답
계정마다 키 하나, 모든 호출에 같은 형태의 응답입니다.
키 위치
키는 SMS8 대시보드의 API 페이지에 표시됩니다. 키는 비밀번호처럼 다루고, 공개 웹페이지가 아니라 서버에 보관하세요.
키 전송 방법
OpenAPI 파일에 나온 대로 X-Api-Key 헤더에 넣으세요. Authorization 헤더의 bearer 토큰이나 key라는 폼 필드도 작동합니다.
응답 내용
성공 플래그가 담긴 JSON입니다. 성공하면 메시지나 레코드를 받습니다. 실패하면 코드와 짧은 메시지가 담긴 오류를 받습니다.
플래그 확인
잘못된 필드나 크레딧 부족 같은 일부 오류는 정상 응답 안에 담겨 옵니다. 결과를 믿기 전에 성공 플래그를 확인하세요.
키가 틀렸을 때
키가 없거나 유효하지 않으면 401을 반환합니다. 필드가 빠졌거나 형식이 잘못되면 400을 반환합니다.
엔드포인트 한눈에 보기
모두 app.sms8.io 아래에 있습니다. 각 엔드포인트의 정확한 필드는 OpenAPI 파일에 있습니다.
| 경로 | 메서드 | 기능 |
|---|---|---|
| /api/v1/messages | POST | 한 사람 또는 여러 사람에게 SMS나 MMS 발송 |
| /api/v1/messages/read | POST | 번호, 방향, 날짜로 필터링한 송수신 메시지 목록 |
| /api/v1/messages/resend | POST | ID로 실패한 메시지 재시도 |
| /api/v1/devices | GET | 배터리, 신호, SIM, 마지막 접속 시간이 포함된 페어링 휴대폰 목록 |
| /api/v1/contacts | POST | 태그와 사용자 정의 필드로 연락처 생성 또는 업데이트 |
| /api/v1/ussd/send | POST | 페어링된 SIM에서 USSD 코드를 실행하고 통신사 응답 받기 |
| /api/v1/ussd/list | POST | 최근 USSD 세션 목록 |
메시지 발송, 필드별 설명
필수 항목은 번호와 내용뿐입니다. 나머지는 모두 기본값이 있습니다.
번호와 내용
번호는 +14155550100처럼 국제 형식으로 넣습니다. 내용은 최대 1,000자이며 {first_name} 같은 병합 태그를 쓸 수 있습니다.
SMS 또는 MMS
유형은 기본값이 sms입니다. MMS에는 공개 HTTPS 이미지 링크를 추가하세요. SMS8이 발송 전에 각 이미지를 1,280픽셀로 조정합니다.
발송할 휴대폰
기기 ID 하나 이상과 SIM 슬롯을 지정하세요. 0은 SIM 1, 1은 SIM 2입니다. 비워 두면 기본 휴대폰이 발송합니다.
순환 발송
모든 휴대폰을 번갈아 쓰거나, 모든 휴대폰의 모든 SIM을 번갈아 쓰도록 옵션을 설정하세요. 메시지마다 무작위 휴대폰도 가능합니다.
우선 발송
메시지를 우선순위로 표시하면 그 휴대폰에서 대기 중인 다른 메시지보다 먼저 나갑니다. 알림과 인증번호에 유용합니다.
돌아오는 값
나중에 조회할 메시지 ID, 메시지를 맡은 휴대폰과 SIM, 대기열에 들어간 시간입니다. 이후 상태는 대기, 발송 중, 발송됨, 전달됨 또는 실패로 바뀝니다.
웹훅
URL을 등록하면 SMS8이 이벤트가 생길 때마다 그 URL로 보냅니다. 웹훅마다 받을 이벤트를 고르고 자체 서명 비밀 키를 받으므로, 모든 요청이 정말 SMS8에서 왔는지 확인하실 수 있습니다.
수신
휴대폰 중 하나에 답장이나 새 메시지가 도착했습니다. 대부분의 CRM 설정에 필요한 이벤트입니다.
발송
휴대폰이 메시지를 받아 SIM 대기열에 넣었습니다. 감사 기록에 좋습니다.
전달
수신자의 통신사가 전달을 확인했습니다.
실패
잘못된 번호나 신호 없음 등으로 재시도 후에도 메시지를 보내지 못했습니다.
USSD 응답
보내신 USSD 코드에 통신사가 응답했습니다.
휴대폰 페어링
새 휴대폰이 계정에 추가되었습니다.
서명, 재시도, 기록
모든 웹훅 요청에는 X-Signature 헤더가 있습니다. API 키가 아니라 해당 웹훅의 비밀 키로 만든, 원본 요청 본문의 HMAC-SHA256 해시입니다. 서버에서 같은 해시를 계산해 상수 시간 비교로 둘을 비교하고, 일치하지 않는 요청은 버리세요.
수신 서버는 HTTPS를 써야 하며 10초 안에 2xx 상태로 응답해야 합니다. 그렇지 않으면 SMS8이 몇 분에서 최대 30일까지 점점 늘어나는 간격으로 다시 시도합니다. 시도마다 상태와 응답이 전송 기록에 표시되며, 어떤 행이든 직접 재시도하실 수 있습니다.
먼저 응답하고, CRM 조회나 AI 분류 같은 느린 작업은 나중에 하세요. 메시지 ID를 고유 키로 써서 재시도된 이벤트가 두 번 처리되지 않게 하세요.
SDK와 언어
웹 요청을 보낼 수 있는 언어라면 무엇이든 됩니다. 아래 도구들은 설정 시간을 줄여 줍니다.
Node와 TypeScript
npm에서 sms8-sdk를 설치하세요. SDK, 명령줄 도구, React 헬퍼, MCP 브리지가 패키지 하나에 들어 있습니다.
02PHP
모든 엔드포인트용 메서드가 있는 PHP 클래스 하나입니다. 파일을 저장하고 require한 뒤 보내세요. PHP 7.4 이상에서 실행되고 curl 확장만 필요하므로 Laravel, WordPress, Symfony, 일반 스크립트에 모두 맞습니다.
03C#과 .NET
HttpClient 기반의 비동기 메서드를 갖춘 클래스 하나입니다. 최신 .NET, .NET Framework 4.6.2 이상, Unity, Xamarin, MAUI에서 실행됩니다.
04Python과 기타 언어
참조 문서에 각 요청이 언어별로 복사할 수 있게 나와 있습니다. 대시보드 빌더로 실제 계정에 요청을 시험해 보실 수 있습니다.
AI 에이전트를 위해
mcp.sms8.io의 SMS8 MCP 서버를 통해 Claude, Cursor 등 AI 도구가 SMS 발송, OTP 인증번호 발송과 확인, 메시지 읽기, 휴대폰 목록 확인, 웹훅 설정을 할 수 있습니다.
같은 API 키를 bearer 토큰으로 보내 사용합니다. AI 도구에 한 번 추가하면 에이전트가 고객님의 번호로 문자를 보낼 수 있습니다.
모든 요청에 API 키를 함께 보내세요. 키는 대시보드의 API 페이지에 있습니다. MCP 서버는 같은 키를 bearer 토큰으로 받습니다.
API에는 인위적인 제한이 없습니다. 실제 속도는 SIM이 정합니다. 큰 발송에는 휴대폰을 추가하시거나 설정에서 메시지 간 지연 시간을 정하세요.
웹훅으로 전달 및 실패 이벤트를 구독하시거나, ID로 메시지를 조회하세요.
네. 유형을 MMS로 정하고 공개 이미지 링크를 추가하세요. SMS8이 발송 전에 이미지 크기를 조정합니다.
네. 현재 엔드포인트는 /api/v1 아래에 있으며, 예전 URL은 기존 앱을 위해 계속 작동합니다.
아니요. 웹훅마다 만들 때 정해지는 자체 서명 비밀 키가 있습니다. API 키는 SMS8로 보내는 요청 밖으로 나가지 않습니다.
이벤트는 재시도 대기열에서 기다리고, SMS8은 최대 30일 동안 계속 시도합니다. 서버가 돌아온 뒤 기록에서 어떤 전송이든 다시 보내실 수도 있습니다.
네. OpenAPI 파일을 Postman, Insomnia 또는 코드 생성기로 가져오면 모든 엔드포인트와 필드를 얻을 수 있습니다.
네. 기기 ID와 SIM 슬롯을 넘기시거나, 부하를 나누도록 SMS8이 휴대폰과 SIM을 번갈아 쓰게 하세요.