문자 API 연동 가이드 | 고르는 기준 6가지와 연동 흐름 5단계

문자 API는 내 서버에서 HTTP 요청 한 번으로 SMS·LMS·알림톡을 보내는 인터페이스예요. 인증 방식, 발신번호 사전등록, 응답값·상태 조회, 예약·분할, 대체 발송, 요금 등 고르는 기준 6가지와 API Key 발급부터 테스트 발송·에러 처리까지 연동 5단계를 정리했어요.

센드온 노트 에디터

Oct 13, 2026

Contents

문자 API란? 웹 발송과 무엇이 다른가요 문자 API 고르는 기준 6가지 ① 인증 방식: API Key를 어디에 어떻게 넣는가 ② 발신번호 사전등록: 코드보다 먼저 끝나 있어야 하는 것 ③ 응답값과 상태 조회: 실패했을 때 무엇이 돌아오는가 ④ 예약·분할·개인화를 요청 한 번으로 ⑤ 알림톡 API와 대체 발송 ⑥ 요금과 과금 기준 문자 API 연동 흐름 5단계 요청과 응답은 어떻게 생겼나요 문자 API 응답 코드와 에러 처리 방법 운영에서 지켜야 할 규칙 5가지 센드온 문자 API로 연동하면 어떻게 되나요 문자 API 연동 자주 묻는 질문 문자 API는 무료로 쓸 수 있나요?개인도 문자 API를 연동할 수 있나요?알림톡 API와 문자 API는 무엇이 다른가요?문자가 실제로 도착했는지 API로 확인할 수 있나요?API로 광고 문자를 보낼 때 주의할 점은 무엇인가요?정리: 문자 API, 이 순서로 고르고 연동하세요

주문이 들어오면 자동으로 "주문이 접수되었습니다" 문자가 나가게 하고 싶거나, 회원가입 인증번호를 내 서비스에서 바로 보내고 싶을 때 찾게 되는 것이 문자 API예요. 그런데 서비스마다 문서 구조가 다르고, 어떤 기준으로 골라야 연동 뒤에 고생하지 않는지 한눈에 보이지 않아요.

결론부터 말하면, 문자 API는 내 서버에서 HTTP 요청 한 번으로 문자 발송 서비스에 "이 번호들에게 이 문구를 보내 달라"고 맡기는 인터페이스예요. 고를 때는 ① 인증 방식 ② 발신번호 사전등록 절차 ③ 응답값과 상태 조회 ④ 예약·분할·개인화 ⑤ 알림톡 대체 발송 ⑥ 요금·과금 기준, 이 여섯 가지를 보면 되고, 연동은 계정 준비 → 발신번호 등록 → 포인트·단가 확인 → 테스트 발송 → 상태 조회·에러 처리 순서로 진행하면 첫 요청부터 200 응답을 받을 수 있어요.

이 글의 HTTP 상태 코드 정의는 MDN 웹 문서를, 발신번호 규정은 전기통신사업법 제84조의2와 법제처 생활법령정보를 기준으로 했고, API 구조 예시는 2026년 10월 기준 센드온 API 명세(OpenAPI)에서 확인한 내용만 썼어요. 사용자가 브라우저에서 직접 보내는 웹 발송과의 차이가 먼저 궁금하다면 웹문자란? [Web발신] 뜻과 차이를 함께 보세요.

문자 API를 고르는 질문은 "어느 서비스가 좋은가"보다 "실패했을 때 무엇이 돌아오는가"예요. 응답값과 상태 조회가 명확한 API가 운영에서 가장 적게 손이 갑니다.

문자 API란? 웹 발송과 무엇이 다른가요

문자 API는 문자 발송 서비스가 외부 프로그램을 위해 열어 둔 HTTP 인터페이스예요. 내 서버가 정해진 주소(엔드포인트)로 발신번호·수신번호·본문을 JSON으로 보내면, 서비스 서버가 통신사로 문자를 전달하고 결과를 JSON으로 돌려줍니다. 사람이 브라우저에서 명단을 올리고 발송 버튼을 누르는 웹 발송과 "문자가 서비스 서버에서 나간다"는 점은 같고, 다른 점은 발송을 사람이 아니라 내 시스템의 이벤트(주문 완료, 예약 확정, 인증 요청)가 자동으로 일으킨다는 것이에요.

웹 발송과 API 발송의 문자 경로 비교 - 웹 발송은 사람이 명단을 올리고 발송 버튼을 눌러 서비스 서버가 통신사로 전달하고 결과 화면에서 확인, API 발송은 내 시스템의 이벤트가 HTTP 요청을 자동 전송해 서비스 서버가 통신사로 전달하고 groupId를 반환하며 상태 조회 API로 성공 실패 수신거부 건수를 코드로 확인

구분	웹 발송 (브라우저 콘솔)	API 발송
발송을 일으키는 것	사람이 버튼 클릭	내 시스템의 이벤트 (주문·예약·인증)
준비물	가입, 발신번호 등록	가입, 발신번호 등록 + API Key, 개발
개인화	주소록 변수(#{이름})	요청마다 수신자별 본문 생성 가능
결과 확인	결과 화면에서 사람이 조회	상태 조회 API로 코드가 자동 조회
어울리는 경우	비정기 공지, 마케팅 일괄 발송	건별 즉시 발송, 반복 발송, 시스템 연동
요금	건당 과금 (동일)	건당 과금 (동일, API 이용료 없는 서비스가 일반적)

표에서 보듯 요금과 발신번호 규정은 두 방식이 같아요. 그래서 "API를 쓰면 더 싸다"가 아니라 "사람 손을 거치지 않고, 내 데이터로 개인화해서, 결과를 코드로 받는다"가 API의 가치예요. 월 몇 번 보내는 공지라면 웹 발송이 더 빠르고, 하루에도 수십 번 건별로 나가는 문자라면 API가 맞습니다.

문자 API 고르는 기준 6가지

문자 API는 "보낼 수 있느냐"는 어디나 비슷해요. 차이는 인증을 어떻게 하는지, 발신번호를 어떻게 등록하는지, 실패했을 때 무엇이 돌아오는지, 예약·분할·개인화를 요청 한 번으로 할 수 있는지, 알림톡 실패 시 문자로 대체되는지, 요금이 성공 건 기준인지에서 납니다. 여섯 가지를 문서에서 먼저 확인하면 연동 뒤 운영에서 생기는 문제의 대부분을 미리 걸러낼 수 있어요.

기준	확인할 것	문서에서 찾는 키워드
① 인증 방식	API Key를 어떤 헤더로 보내는지, 키가 계정당 몇 개인지, 허용 IP 제한이 있는지	Authorization, Basic, Bearer, API Key, IP 화이트리스트
② 발신번호 사전등록	등록 절차·서류, 심사 시간, 미등록 번호로 요청하면 어떤 응답인지	발신번호, 사전등록, 인증 서류
③ 응답값·상태 조회	요청 직후 돌아오는 ID, 그 ID로 성공·실패·수신거부 건수를 조회하는 API	groupId, messageId, status, 조회
④ 예약·분할·개인화	요청에 예약 시각, 분할 간격, 야간 금지, 변수 치환을 넣을 수 있는지	reservation, repeat, interval, 변수
⑤ 알림톡·대체 발송	알림톡 실패 시 SMS/LMS로 자동 대체되는지, 템플릿 검수 API가 있는지	fallback, 대체문자, 템플릿
⑥ 요금·과금 기준	성공 건만 과금인지, 실패 환급, 단가 조회 API 유무	단가, 포인트, 환급

① 인증 방식: API Key를 어디에 어떻게 넣는가

문자 API 인증은 대부분 발급받은 API Key를 HTTP 헤더에 실어 보내는 방식이에요. 계정 ID와 키를 함께 쓰는 HTTP Basic 인증, 키만 Bearer 토큰으로 보내는 방식, 요청마다 서명을 만드는 HMAC 방식이 있고, 어느 쪽이든 키는 소스 코드가 아니라 환경 변수나 비밀 관리 도구에 두어야 해요. 확인할 것은 세 가지예요. 키를 계정당 몇 개 만들 수 있는지(센드온은 계정별 1개), 허용 IP 목록을 등록해야 하는지(등록하지 않은 서버에서 보내면 403이 돌아와요), 키가 유출됐을 때 바로 재발급·폐기할 수 있는지입니다.

② 발신번호 사전등록: 코드보다 먼저 끝나 있어야 하는 것

API로 보내는 문자도 발신번호는 반드시 사전에 등록·승인된 번호여야 해요. 전기통신사업법 제84조의2는 전화번호 거짓표시를 금지하고 통신사·문자 발송 사업자에게 이를 막을 기술적 조치를 요구하며, 법제처 안내에 따르면 2015년 4월 16일 시행된 개정법으로 문자메시지 발신번호를 임의로 변경할 수 없게 되었고 위반 시 3년 이하의 징역 또는 1억 원 이하의 벌금이에요. KISA는 발신번호 거짓표시 신고센터와 차단 시스템을 운영합니다. 그래서 요청의 발신번호 값에 등록되지 않은 번호를 넣으면 코드를 아무리 고쳐도 발송되지 않아요. 가입 시 본인인증한 휴대폰 번호는 자동 등록되는 서비스가 많고, 유선·대표번호는 통신서비스 이용증명원 같은 서류를 내고 심사를 받습니다. 유형별 서류와 절차는 사업자 문자발송 절차 총정리에 정리해두었어요.

③ 응답값과 상태 조회: 실패했을 때 무엇이 돌아오는가

발송 요청이 200으로 접수됐다는 것과 문자가 휴대폰에 도착했다는 것은 다른 일이에요. 요청 직후에는 "접수됐고 이 ID로 추적하라"는 그룹 ID나 메시지 ID만 돌아오고, 통신사 전달 결과는 몇 초에서 몇 분 뒤에 확정됩니다. 그래서 좋은 문자 API는 ID로 다시 조회하는 상태 조회 API를 반드시 갖추고, 조회 결과에 대기·발송 중·성공·실패·취소·수신거부 건수와 차감·환급 포인트가 함께 나와요. 이 구조가 없으면 "보냈는데 안 왔다"는 문의에 답할 방법이 없습니다.

④ 예약·분할·개인화를 요청 한 번으로

수천 건을 한 번에 보내거나, 아침 9시에 맞춰 보내거나, 받는 사람마다 이름을 넣는 일을 내 코드로 전부 구현하면 복잡해져요. 요청 본문에 예약 시각, 분할 발송(한 번에 보낼 건수·간격·단위), 야간 발송 금지, 변수 치환 설정을 넣을 수 있는 API라면 내 쪽 코드는 요청 한 번으로 끝나요. 특히 광고성 문자는 정보통신망법 제50조에 따라 오후 9시부터 다음 날 오전 8시까지 별도 동의 없이는 보낼 수 없으니, 야간 금지 옵션이 요청에 있으면 운영 사고를 하나 줄일 수 있어요. 대량 발송 시 분할 간격을 어떻게 잡는지는 대량문자 전송 방법 총정리를 참고하세요.

⑤ 알림톡 API와 대체 발송

카카오 알림톡은 문자보다 단가가 낮고 도달이 좋지만, 받는 사람이 카카오톡을 쓰지 않거나 수신을 막아 두면 실패해요. 그래서 알림톡 API를 고를 때는 실패 시 SMS·LMS로 자동 대체 발송(fallback)되는지, 대체 문구를 템플릿에 미리 넣어 둘 수 있는지, 템플릿 등록·검수 요청까지 API로 되는지를 봅니다. 알림톡은 사전 검수된 템플릿으로만 보낼 수 있고 검수에 영업일 기준 1~3일이 걸리므로, 템플릿 관리가 API에 없으면 운영 중에 대시보드를 오가야 해요. 알림톡 발송 조건과 심사 기준은 카카오 알림톡 보내는 법에 정리되어 있습니다.

⑥ 요금과 과금 기준

문자 API는 대부분 API 자체 이용료가 없고 발송 건당 과금이에요. 확인할 것은 "성공 건만 과금하고 실패 건은 환급하는가", "SMS와 LMS의 경계(90바이트)를 넘으면 자동으로 LMS 요금이 적용되는가", "지금 내 계정의 단가를 API로 조회할 수 있는가"예요. 예를 들어 센드온 요금은 SMS 7.4원(가입 후 90일 프로모션가, 이후 10.5원), LMS 24.5원, 알림톡 6.4원이고 발송 성공 건에만 과금하며 실패 건은 100% 환급돼요. 글자수에 따른 SMS·LMS·MMS 구분은 SMS LMS MMS 차이에서 확인할 수 있어요.

문자 API 연동 흐름 5단계

문자 API 연동은 계정 준비 → 발신번호 사전등록 → 포인트·단가 확인 → 테스트 발송 → 상태 조회·에러 처리 순서로 진행해요. 앞의 세 단계는 코드와 무관한 준비 작업인데, 이것이 끝나지 않은 상태에서 첫 요청을 보내면 401이나 403이 돌아와 "코드가 틀렸나" 하고 엉뚱한 곳을 찾게 됩니다. 센드온 개발자 문서의 시작하기 전에 알아야 할 사항도 같은 순서로 준비를 안내하고 있어요.

계정 준비 — 사업자 인증을 마치고 API Key를 발급받아요. 센드온은 마이페이지 › API KEY에서 계정별 1개를 발급하고, 문서에 "API KEY는 민감한 정보입니다. 절대 소스 코드에 직접 포함하지 마세요"라고 명시되어 있어요. 요청을 보낼 서버의 IP를 허용 IP 목록에 등록해야 하는 서비스라면 이 단계에서 함께 등록합니다.
발신번호 사전등록 — 본인인증한 휴대폰 번호는 자동 등록되고, 유선·대표번호·사업자 번호는 발신번호 등록 가이드대로 서류를 올려 승인을 받아요. 요청의 발신번호(from)에는 하이픈 없이 승인된 번호만 넣을 수 있습니다.
포인트·단가 확인 — 선불 포인트를 충전하고, 단가 조회 API가 있으면 호출해서 메시지 타입별 건당 비용을 코드에서 읽어 둬요. 잔액이 떨어지면 발송이 멈추므로 잔액 알림 수신자를 설정해 둡니다.
테스트 발송 — 내 휴대폰 번호로 SMS 1건을 보내 응답 code가 200이고 groupId가 돌아오는지 확인해요. 401이면 키·헤더, 403이면 포인트·IP·발신번호 승인 상태를 다시 보면 됩니다.
상태 조회·에러 처리 — 받은 groupId로 상세 조회를 호출해 성공·실패·수신거부 건수를 확인하고, 429·500은 간격을 두고 재시도, 400은 재시도하지 않고 요청을 고치는 규칙을 코드에 넣어요. 운영 중에는 요청 ID와 응답을 로그로 남겨 문의가 왔을 때 추적할 수 있게 합니다.

요청과 응답은 어떻게 생겼나요

서비스마다 필드 이름은 다르지만 구조는 비슷해요. 아래는 센드온 API 명세(v2) 기준 SMS 발송 요청과 응답 예시입니다. 발신번호는 사전 승인된 번호, 수신번호는 문자열 배열이고, 본문은 SMS가 90바이트(한글 45자), LMS가 2,000바이트(한글 1,000자)까지예요.

POST https://api.sendon.io/v2/messages/sms
Authorization: Basic base64(계정ID:API_KEY)
Content-Type: application/json

{
  "type": "SMS",
  "from": "0212345678",
  "to": ["01012345678", "01087654321"],
  "message": "[센드온] 예약이 확정되었습니다. 10월 20일 14:00",
  "reservation": {
    "datetime": "2026-10-20T09:00:00+09:00",
    "repeat": { "limit": 500, "unit": "MINUTE", "interval": 5, "denyNightTime": true }
  },
  "isAd": false
}

응답은 HTTP 상태와 별도로 본문에 code·message·data가 들어 있고, data의 groupId가 이후 상태 조회의 열쇠예요.

{
  "code": 200,
  "message": "성공",
  "data": {
    "groupId": "004a6217-f06c-40f6-8f39-bf35b3f76111",
    "reservationId": "1"
  }
}

groupId로 상세 조회(GET /v2/messages/sms/groups/{groupId})를 호출하면 그룹 상태(RESERVED·PROCESSING·COMPLETED·FAILED·CANCELED)와 함께 요청 건수, 대기·발송 중·성공·실패·취소·수신거부 건수, 차감 포인트와 환급 포인트가 돌아와요. 이 값들을 내 시스템에 저장해 두면 "누구에게 언제 무엇이 갔는지"를 대시보드 없이도 답할 수 있습니다.

예약 발송 취소는 예약 시각 전에 취소 API를 호출하면 돼요. 센드온 기준 알림톡 예약은 현재 시각 10분 후부터 60일 이내로 설정할 수 있고, 이미 통신사로 넘어간 건은 취소되지 않습니다.

문자 API 응답 코드와 에러 처리 방법

문자 API의 에러 처리는 HTTP 상태 코드를 기준으로 "고쳐서 보낼 것"과 "잠시 후 다시 보낼 것"을 나누는 데서 시작해요. MDN 정의로 400은 잘못된 문법으로 서버가 요청을 이해할 수 없는 상태, 401은 인증이 필요한 상태, 403은 접근 권리가 없는 상태, 429는 지정된 시간에 너무 많은 요청을 보낸 상태, 500은 서버가 처리 방법을 모르는 상황이에요. 400대 중 400·401·403·404는 같은 요청을 다시 보내도 결과가 같으니 원인을 고쳐야 하고, 429와 500대는 간격을 두고 재시도하면 됩니다.

문자 API 응답 코드별 처리 방법 - 200 성공은 상태 조회로 최종 결과 확인, 400 잘못된 요청은 필수값 누락 하이픈 포함 번호 바이트 초과로 요청 본문 수정, 401 인증 실패는 API Key 재확인, 403 권한 없음은 포인트 부족 미등록 IP 미승인 발신번호로 충전 IP 등록 번호 승인, 429 요청 제한 초과는 간격을 늘려 재시도, 500 서버 오류는 잠시 후 재시도

코드	의미 (MDN)	문자 API에서 흔한 원인 (센드온 명세 기준)	처리 방법
200	요청 성공	발송 요청 접수, groupId 반환	상태 조회로 최종 결과 확인
400	잘못된 요청	필수 파라미터 누락, 잘못된 형식, 유효하지 않은 값 (하이픈 포함 번호, 바이트 초과)	요청 본문 수정 후 재요청, 자동 재시도 금지
401	인증 실패	API 키가 유효하지 않거나 만료	키·헤더 형식 재확인, 필요 시 재발급
403	권한 없음	포인트(크레딧) 부족, 채널 미인증, 템플릿 미승인, 허용 IP 미등록	충전·IP 등록·발신번호 승인 후 재요청
404	리소스 없음	템플릿·채널·그룹 ID를 찾을 수 없음	ID 값 확인
429	요청 제한 초과	짧은 시간에 과다 호출 (rate limit)	간격을 늘려 재시도 (지수 백오프)
500	서버 오류	내부 오류 또는 외부(통신사·카카오) API 장애	같은 요청을 잠시 후 재시도, 반복되면 문의

주의할 점이 하나 있어요. 일부 API는 오류가 나도 HTTP 200으로 응답하고 본문의 code나 errorCode로 성공 여부를 알려 줍니다. 센드온 명세에서도 브랜드 메시지 발송 API가 "오류가 발생해도 HTTP 200으로 응답하므로, 본문의 code와 errorCode로 성공 여부를 확인해야 합니다"라고 안내하고 있어요. 그러니 HTTP 상태만 보지 말고 본문의 code 값을 항상 함께 검사하는 것이 안전합니다.

운영에서 지켜야 할 규칙 5가지

키 보관 — API Key는 환경 변수나 비밀 관리 도구에 두고, 저장소에 올리지 않아요. 키가 노출된 것 같으면 바로 재발급합니다.
재시도 규칙 — 429·500만 재시도하고 400·401·403은 재시도하지 않아요. 같은 요청을 무한 반복하면 요청 제한에 걸리거나 중복 발송이 생깁니다.
광고성 문자 표기 — 영리 목적 광고라면 정보통신망법 제50조에 따라 사전 동의, 본문 앞 (광고) 표기, 080 무료수신거부 번호가 필요하고 21~08시 전송은 별도 동의가 있어야 해요. 요청에 광고 여부 플래그(isAd)가 있으면 반드시 맞게 넣습니다. 불법 스팸 신고와 기준은 KISA 불법스팸대응센터에서 확인할 수 있어요.
수신거부 반영 — 수신거부 목록 API가 있으면 내 시스템의 거부 요청을 바로 반영하고, 발송 결과의 수신거부(blocked) 건수를 확인해요.
로그와 모니터링 — 요청 본문(개인정보 제외), groupId, 응답 code를 남기고, 잔액 알림과 실패율 알림을 설정해 둡니다.

센드온 문자 API로 연동하면 어떻게 되나요

센드온은 SMS·LMS·MMS, 카카오 알림톡·브랜드 메시지, RCS를 하나의 API(v2, 기본 주소 https://api.sendon.io)로 제공하는 메시지 발송 서비스예요. 2026년 10월 기준 OpenAPI 명세에 58개 엔드포인트가 있고, 인증은 계정 ID와 API Key를 쓰는 HTTP Basic 방식이에요. 위에서 본 여섯 가지 기준을 센드온에 대입하면 다음과 같습니다.

기준	센드온 API (2026년 10월 명세 기준)
① 인증	HTTP Basic (계정 ID + API Key), 계정별 API Key 1개, 사업자 인증 후 발급, 허용 IP 등록
② 발신번호	사전 등록·승인된 번호만 from에 사용, 발신번호 목록 조회 API(GET /v2/sender/numbers)로 승인 상태 확인
③ 응답·상태 조회	응답 본문 code·message·data(groupId), 그룹 상세 조회로 성공·실패·취소·수신거부 건수와 차감·환급 포인트, 그룹 내 수신자별 결과 조회
④ 예약·분할·개인화	reservation(datetime)+repeat(limit·unit·interval·denyNightTime), 주소록 그룹 발송, #{변수} 치환, CSV 업로드용 presigned URL
⑤ 알림톡·대체 발송	알림톡 1회 최대 1,000명, fallback NONE·TEMPLATE·CUSTOM으로 SMS/LMS/MMS 대체, 템플릿 생성·검수 요청·취소 API
⑥ 요금	SMS 7.4원(90일 후 10.5원)·LMS 24.5원·알림톡 6.4원, 성공 건만 과금·실패 100% 환급, 단가 조회 API(GET /v2/point/costs)

직접 HTTP를 호출해도 되지만, TypeScript SDK(npm 패키지 @alipeople/sendon-sdk-typescript, Node.js 20 이상)와 Java SDK(io.sendon:sendon-sdk-java, JDK 17 이상)를 쓰면 요청 객체 생성과 응답 파싱을 SDK가 대신해 줘요. 공개 저장소 sendon-examples에는 SMS 즉시·예약 발송, 예약 취소, 발송 조회, MMS 이미지 업로드, 알림톡·브랜드 메시지, RCS, 발신번호·단가·포인트 조회, 수신거부 추가·삭제까지 35개 시나리오 예제 코드가 있습니다. TypeScript 예제의 발송 코드는 아래처럼 생겼어요.

import { Sendon, SmsMessageType } from '@alipeople/sendon-sdk-typescript';

const sendon = new Sendon({ id: process.env.USER_ID!, apikey: process.env.USER_APIKEY! });

const result = await sendon.sms.send({
  type: SmsMessageType.SMS,
  from: process.env.SMS_MOBILE_FROM!,      // 사전 등록된 발신번호
  to: ['01012345678'],
  message: '안녕하세요. 예약이 확정되었습니다.',
});

if (result.code === 200) {
  console.log('접수됨, groupId =', result.data.groupId);
}

센드온 API를 쓰려면 사업자 인증이 필요해요. 가입과 발신번호 등록, API Key 발급은 무료이고 발송한 건에만 포인트가 차감되므로, 가입 후 내 번호로 1건을 보내는 테스트까지는 비용이 거의 들지 않습니다. 웹 콘솔 발송과 API 발송이 같은 계정·포인트·주소록을 쓰기 때문에, 마케팅팀은 콘솔에서, 개발팀은 API로 보내면서 결과를 한곳에서 볼 수 있어요. 여러 서비스를 비교해 고르는 기준은 단체문자 발송 사이트 고르는 법에도 정리해두었습니다.

지금 가입하면 사업자 인증 → API Key 발급 → 발신번호 등록까지 바로 진행할 수 있어요. 센드온 무료 가입하고 문자 API 연동 시작하기

문자 API 연동 자주 묻는 질문

문자 API는 무료로 쓸 수 있나요?

문자 API 자체에 이용료를 받는 서비스는 드물고, 대부분 발송 건당 요금만 내요. 센드온도 가입·API Key 발급·발신번호 등록은 무료이고, 발송 성공 건에만 포인트가 차감되며(SMS 7.4원~), 실패 건은 100% 환급됩니다. 다만 선불 포인트 방식이라 잔액이 0이면 요청이 403으로 거절되니, 잔액 알림을 켜 두는 것이 좋아요.

개인도 문자 API를 연동할 수 있나요?

서비스에 따라 달라요. 센드온은 API Key 발급 조건이 사업자 인증 완료라서 개인 회원은 사업자 전환 후 이용할 수 있어요. 어느 서비스든 발신번호는 전기통신사업법 제84조의2에 따라 본인·사업자 명의로 사전 등록된 번호만 쓸 수 있고, 가입 시 본인인증한 휴대폰 번호는 보통 자동으로 등록됩니다.

알림톡 API와 문자 API는 무엇이 다른가요?

문자 API는 등록된 발신번호와 본문만 있으면 바로 보낼 수 있지만, 알림톡 API는 카카오 채널 등록과 사전 검수된 템플릿이 필요해요. 검수에는 영업일 기준 1~3일이 걸리고, 승인된 템플릿의 변수 자리에만 값을 넣어 보낼 수 있습니다. 대신 단가가 낮고(센드온 6.4원), 실패 시 SMS·LMS로 자동 대체 발송(fallback)을 설정할 수 있어 두 API를 함께 쓰는 경우가 많아요.

문자가 실제로 도착했는지 API로 확인할 수 있나요?

발송 요청 응답은 "접수"까지만 알려 주고, 도착 결과는 상태 조회 API로 확인해요. 센드온은 응답의 groupId로 그룹 상세를 조회하면 요청 건수와 대기·발송 중·성공·실패·취소·수신거부 건수, 차감·환급 포인트가 나오고, 그룹 내 수신자별 전송 상태와 오류 사유도 따로 조회할 수 있습니다. 결과가 확정될 때까지 몇 초에서 몇 분 걸리니, 요청 직후가 아니라 잠시 뒤에 조회하도록 코드를 짜세요.

API로 광고 문자를 보낼 때 주의할 점은 무엇인가요?

광고성 문자는 정보통신망법 제50조에 따라 수신자의 사전 동의가 있어야 하고, 본문 앞 (광고) 표기와 080 무료수신거부 번호를 넣어야 하며, 오후 9시~다음 날 오전 8시에는 별도 동의 없이 보낼 수 없어요. API 요청의 광고 여부 플래그(센드온은 isAd)를 맞게 넣고, 예약 발송에는 야간 금지 옵션(denyNightTime)을 켜 두며, 수신거부 목록을 API로 반영해 거부한 번호에 다시 보내지 않도록 해야 합니다. 위반 시 과태료는 사업자 문자발송 절차 글에 정리해두었어요.

정리: 문자 API, 이 순서로 고르고 연동하세요

문자 API는 내 시스템의 이벤트가 자동으로 문자를 보내게 하는 HTTP 인터페이스예요. 고를 때는 인증 방식, 발신번호 사전등록, 응답값과 상태 조회, 예약·분할·개인화, 알림톡 대체 발송, 요금 기준 여섯 가지를 문서에서 확인하고, 연동은 계정 준비 → 발신번호 등록 → 포인트·단가 확인 → 테스트 발송 → 상태 조회·에러 처리 순서로 진행하면 됩니다. 에러는 400·401·403은 고쳐서, 429·500은 기다렸다 다시 보내고, HTTP 200이어도 본문 code를 함께 확인하는 습관이 운영을 편하게 해 줘요.

센드온 API는 문자·알림톡·RCS를 하나의 키로 보내고, TypeScript·Java SDK와 공개 예제로 첫 발송까지의 거리를 줄여 줍니다. 아래에서 가입하고 내 번호로 테스트 1건부터 보내 보세요.

Contents

문자발송가이드 발송방법비교

문자 API 연동 가이드 | 고르는 기준 6가지와 연동 흐름 5단계

센드온 노트 에디터

Oct 13, 2026

Contents

문자 API를 고르는 질문은 "어느 서비스가 좋은가"보다 "실패했을 때 무엇이 돌아오는가"예요. 응답값과 상태 조회가 명확한 API가 운영에서 가장 적게 손이 갑니다.

문자 API란? 웹 발송과 무엇이 다른가요

구분	웹 발송 (브라우저 콘솔)	API 발송
발송을 일으키는 것	사람이 버튼 클릭	내 시스템의 이벤트 (주문·예약·인증)
준비물	가입, 발신번호 등록	가입, 발신번호 등록 + API Key, 개발
개인화	주소록 변수(#{이름})	요청마다 수신자별 본문 생성 가능
결과 확인	결과 화면에서 사람이 조회	상태 조회 API로 코드가 자동 조회
어울리는 경우	비정기 공지, 마케팅 일괄 발송	건별 즉시 발송, 반복 발송, 시스템 연동
요금	건당 과금 (동일)	건당 과금 (동일, API 이용료 없는 서비스가 일반적)

문자 API 고르는 기준 6가지

기준	확인할 것	문서에서 찾는 키워드
① 인증 방식	API Key를 어떤 헤더로 보내는지, 키가 계정당 몇 개인지, 허용 IP 제한이 있는지	Authorization, Basic, Bearer, API Key, IP 화이트리스트
② 발신번호 사전등록	등록 절차·서류, 심사 시간, 미등록 번호로 요청하면 어떤 응답인지	발신번호, 사전등록, 인증 서류
③ 응답값·상태 조회	요청 직후 돌아오는 ID, 그 ID로 성공·실패·수신거부 건수를 조회하는 API	groupId, messageId, status, 조회
④ 예약·분할·개인화	요청에 예약 시각, 분할 간격, 야간 금지, 변수 치환을 넣을 수 있는지	reservation, repeat, interval, 변수
⑤ 알림톡·대체 발송	알림톡 실패 시 SMS/LMS로 자동 대체되는지, 템플릿 검수 API가 있는지	fallback, 대체문자, 템플릿
⑥ 요금·과금 기준	성공 건만 과금인지, 실패 환급, 단가 조회 API 유무	단가, 포인트, 환급

① 인증 방식: API Key를 어디에 어떻게 넣는가

② 발신번호 사전등록: 코드보다 먼저 끝나 있어야 하는 것

③ 응답값과 상태 조회: 실패했을 때 무엇이 돌아오는가

④ 예약·분할·개인화를 요청 한 번으로

⑤ 알림톡 API와 대체 발송

⑥ 요금과 과금 기준

문자 API 연동 흐름 5단계

계정 준비 — 사업자 인증을 마치고 API Key를 발급받아요. 센드온은 마이페이지 › API KEY에서 계정별 1개를 발급하고, 문서에 "API KEY는 민감한 정보입니다. 절대 소스 코드에 직접 포함하지 마세요"라고 명시되어 있어요. 요청을 보낼 서버의 IP를 허용 IP 목록에 등록해야 하는 서비스라면 이 단계에서 함께 등록합니다.
발신번호 사전등록 — 본인인증한 휴대폰 번호는 자동 등록되고, 유선·대표번호·사업자 번호는 발신번호 등록 가이드대로 서류를 올려 승인을 받아요. 요청의 발신번호(from)에는 하이픈 없이 승인된 번호만 넣을 수 있습니다.
포인트·단가 확인 — 선불 포인트를 충전하고, 단가 조회 API가 있으면 호출해서 메시지 타입별 건당 비용을 코드에서 읽어 둬요. 잔액이 떨어지면 발송이 멈추므로 잔액 알림 수신자를 설정해 둡니다.
테스트 발송 — 내 휴대폰 번호로 SMS 1건을 보내 응답 code가 200이고 groupId가 돌아오는지 확인해요. 401이면 키·헤더, 403이면 포인트·IP·발신번호 승인 상태를 다시 보면 됩니다.
상태 조회·에러 처리 — 받은 groupId로 상세 조회를 호출해 성공·실패·수신거부 건수를 확인하고, 429·500은 간격을 두고 재시도, 400은 재시도하지 않고 요청을 고치는 규칙을 코드에 넣어요. 운영 중에는 요청 ID와 응답을 로그로 남겨 문의가 왔을 때 추적할 수 있게 합니다.

요청과 응답은 어떻게 생겼나요

POST https://api.sendon.io/v2/messages/sms
Authorization: Basic base64(계정ID:API_KEY)
Content-Type: application/json

{
  "type": "SMS",
  "from": "0212345678",
  "to": ["01012345678", "01087654321"],
  "message": "[센드온] 예약이 확정되었습니다. 10월 20일 14:00",
  "reservation": {
    "datetime": "2026-10-20T09:00:00+09:00",
    "repeat": { "limit": 500, "unit": "MINUTE", "interval": 5, "denyNightTime": true }
  },
  "isAd": false
}

응답은 HTTP 상태와 별도로 본문에 code·message·data가 들어 있고, data의 groupId가 이후 상태 조회의 열쇠예요.

{
  "code": 200,
  "message": "성공",
  "data": {
    "groupId": "004a6217-f06c-40f6-8f39-bf35b3f76111",
    "reservationId": "1"
  }
}

문자 API 응답 코드와 에러 처리 방법

코드	의미 (MDN)	문자 API에서 흔한 원인 (센드온 명세 기준)	처리 방법
200	요청 성공	발송 요청 접수, groupId 반환	상태 조회로 최종 결과 확인
400	잘못된 요청	필수 파라미터 누락, 잘못된 형식, 유효하지 않은 값 (하이픈 포함 번호, 바이트 초과)	요청 본문 수정 후 재요청, 자동 재시도 금지
401	인증 실패	API 키가 유효하지 않거나 만료	키·헤더 형식 재확인, 필요 시 재발급
403	권한 없음	포인트(크레딧) 부족, 채널 미인증, 템플릿 미승인, 허용 IP 미등록	충전·IP 등록·발신번호 승인 후 재요청
404	리소스 없음	템플릿·채널·그룹 ID를 찾을 수 없음	ID 값 확인
429	요청 제한 초과	짧은 시간에 과다 호출 (rate limit)	간격을 늘려 재시도 (지수 백오프)
500	서버 오류	내부 오류 또는 외부(통신사·카카오) API 장애	같은 요청을 잠시 후 재시도, 반복되면 문의

운영에서 지켜야 할 규칙 5가지

키 보관 — API Key는 환경 변수나 비밀 관리 도구에 두고, 저장소에 올리지 않아요. 키가 노출된 것 같으면 바로 재발급합니다.
재시도 규칙 — 429·500만 재시도하고 400·401·403은 재시도하지 않아요. 같은 요청을 무한 반복하면 요청 제한에 걸리거나 중복 발송이 생깁니다.
광고성 문자 표기 — 영리 목적 광고라면 정보통신망법 제50조에 따라 사전 동의, 본문 앞 (광고) 표기, 080 무료수신거부 번호가 필요하고 21~08시 전송은 별도 동의가 있어야 해요. 요청에 광고 여부 플래그(isAd)가 있으면 반드시 맞게 넣습니다. 불법 스팸 신고와 기준은 KISA 불법스팸대응센터에서 확인할 수 있어요.
수신거부 반영 — 수신거부 목록 API가 있으면 내 시스템의 거부 요청을 바로 반영하고, 발송 결과의 수신거부(blocked) 건수를 확인해요.
로그와 모니터링 — 요청 본문(개인정보 제외), groupId, 응답 code를 남기고, 잔액 알림과 실패율 알림을 설정해 둡니다.

센드온 문자 API로 연동하면 어떻게 되나요

기준	센드온 API (2026년 10월 명세 기준)
① 인증	HTTP Basic (계정 ID + API Key), 계정별 API Key 1개, 사업자 인증 후 발급, 허용 IP 등록
② 발신번호	사전 등록·승인된 번호만 from에 사용, 발신번호 목록 조회 API(GET /v2/sender/numbers)로 승인 상태 확인
③ 응답·상태 조회	응답 본문 code·message·data(groupId), 그룹 상세 조회로 성공·실패·취소·수신거부 건수와 차감·환급 포인트, 그룹 내 수신자별 결과 조회
④ 예약·분할·개인화	reservation(datetime)+repeat(limit·unit·interval·denyNightTime), 주소록 그룹 발송, #{변수} 치환, CSV 업로드용 presigned URL
⑤ 알림톡·대체 발송	알림톡 1회 최대 1,000명, fallback NONE·TEMPLATE·CUSTOM으로 SMS/LMS/MMS 대체, 템플릿 생성·검수 요청·취소 API
⑥ 요금	SMS 7.4원(90일 후 10.5원)·LMS 24.5원·알림톡 6.4원, 성공 건만 과금·실패 100% 환급, 단가 조회 API(GET /v2/point/costs)

import { Sendon, SmsMessageType } from '@alipeople/sendon-sdk-typescript';

const sendon = new Sendon({ id: process.env.USER_ID!, apikey: process.env.USER_APIKEY! });

const result = await sendon.sms.send({
  type: SmsMessageType.SMS,
  from: process.env.SMS_MOBILE_FROM!,      // 사전 등록된 발신번호
  to: ['01012345678'],
  message: '안녕하세요. 예약이 확정되었습니다.',
});

if (result.code === 200) {
  console.log('접수됨, groupId =', result.data.groupId);
}

지금 가입하면 사업자 인증 → API Key 발급 → 발신번호 등록까지 바로 진행할 수 있어요. 센드온 무료 가입하고 문자 API 연동 시작하기