# 샌드고 (Sendgo)

> 샌드고는 카카오 알림톡·친구톡과 SMS/LMS/MMS를 발송하는 한국 메시지 발송 플랫폼입니다. 20개 언어·프레임워크용 공식 SDK와 REST API를 제공합니다.

각 항목은 해당 SDK 가이드의 마크다운 원문입니다. 언어를 고른 뒤 설치 명령과 발송 예제를 그대로 사용할 수 있습니다. 인증은 액세스 키/시크릿 키로 토큰을 발급받아 Bearer 토큰으로 호출하며, SDK가 발급과 갱신을 자동 처리합니다. API 버전은 v2를 권장합니다.

## Quickstart for coding agents

- Base URL: `https://sendgo.io/api`. Version segment is `v1` or `v2` — **use `v2`**.
- Auth: `POST /api/v2/token` with `Authorization: Basic base64(accessKey:secretKey)`,
  then `Authorization: Bearer <token>` on every other call (v1 wants `base64(token)` instead).
  Official SDKs cache the token, refresh it and retry once on 401/403 — do not hand-roll that.

| Purpose | Endpoint |
| --- | --- |
| Issue token | `POST /api/v2/token` |
| Kakao Alimtalk | `POST /api/v2/notices/send` |
| Kakao Brand Message | `POST /api/v2/brand-messages/send` |
| SMS / LMS / MMS | `POST /api/v2/messages/send` |
| Short URL | `POST /api/v2/short-urls` |

```ts
import Sendgo from '@sendgo/node';   // default export, not a named one

const sendgo = new Sendgo({
  accessKey:      process.env.SENDGO_ACCESS_KEY!,
  secretKey:      process.env.SENDGO_SECRET_KEY!,
  kakaoSenderKey: process.env.SENDGO_KAKAO_SENDER_KEY,
  smsSenderKey:   process.env.SENDGO_SMS_SENDER_KEY,
  apiVersion:     'v2',
});

await sendgo.alimtalk.send({
  templateCode: 'ORDER_CONFIRM_001',
  contacts: [{ contact: '01012345678', name: '홍길동', var1: 'ORD-001' }],
});
```

Rules that decide whether the code works:

1. Alimtalk sends only to a **template approved in advance**; you fill `var1`–`var8`,
   you do not write the body. A wrong code returns `INVALID_TEMPLATE_CODE`.
2. The **sending number must be pre-registered** (Korean law). Unregistered numbers fail
   at send time, not at signup.
3. Phone numbers are **digits only** — `01012345678`, never `010-1234-5678`.
4. `replaceSms: "Y"` also needs `smsSubject` and `smsContent`, or the fallback sends nothing.
5. **Friendtalk ended 2025-12-31.** New code uses Brand Message. The exception: free-form
   types (`FT`/`FI`/`FW`) to individual recipients still go through `/api/v2/friends/send`;
   the brand-message endpoint answers `NOT_A_BRAND_MESSAGE` for that combination.
6. Advertising messages need a `(광고)` prefix, a free opt-out number, and must not be sent
   between 21:00 and 08:00 KST. Transactional Alimtalk is exempt.
7. `402 PAYMENT_REQUIRED` means the credit balance ran out. Retrying will not help.

## Which package to install

| Language / framework | Package | Install |
| --- | --- | --- |
| PHP (PHP) | `sendgo/php` | `composer require sendgo/php` |
| Laravel (PHP) | `sendgo/laravel` | `composer require sendgo/laravel` |
| Symfony (PHP) | `sendgo/symfony` | `composer require sendgo/symfony` |
| WordPress (PHP) | `sendgo/wordpress` | `composer require sendgo/wordpress` |
| Node.js (JavaScript / TypeScript) | `@sendgo/node` | `npm install @sendgo/node` |
| React / Next.js (JavaScript / TypeScript) | `@sendgo/react` | `npm install @sendgo/react` |
| Vue / Nuxt (JavaScript / TypeScript) | `@sendgo/vue` | `npm install @sendgo/vue` |
| NestJS (JavaScript / TypeScript) | `@sendgo/nestjs` | `npm install @sendgo/nestjs` |
| Python (Python) | `sendgo-python` | `pip install sendgo-python` |
| Django (Python) | `sendgo-django` | `pip install sendgo-django` |
| FastAPI (Python) | `sendgo-fastapi` | `pip install sendgo-fastapi` |
| Go (Go) | `github.com/send-go/go` | `go get github.com/send-go/go` |
| Java (Java) | `io.sendgo:sendgo-java` | `implementation "io.sendgo:sendgo-java:1.1.0"` |
| Spring Boot (Java) | `io.sendgo:sendgo-spring` | `implementation "io.sendgo:sendgo-spring:1.0.1"` |
| Ruby (Ruby) | `sendgo` | `gem install sendgo` |
| Ruby on Rails (Ruby) | `sendgo-rails` | `bundle add sendgo-rails` |
| .NET (C# / .NET) | `Sendgo.SDK` | `dotnet add package Sendgo.SDK` |
| ASP.NET Core (C# / .NET) | `Sendgo.AspNetCore` | `dotnet add package Sendgo.AspNetCore` |
| Flutter / Dart (Dart) | `sendgo_flutter` | `dart pub add sendgo_flutter` |

Framework packages pull their core in. Install one, not both.

## SDK 가이드

### 서버 코어 SDK

- [PHP (sendgo/php)](https://sendgo.io/ko/sdk/php.md): PHP에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 순수 PHP SDK
- [Node.js (@sendgo/node)](https://sendgo.io/ko/sdk/node.md): Node.js / TypeScript에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK
- [Python (sendgo-python)](https://sendgo.io/ko/sdk/python.md): Python / Django / FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 SDK
- [Go (github.com/send-go/go)](https://sendgo.io/ko/sdk/go.md): Go에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Go SDK
- [Java (io.sendgo:sendgo-java)](https://sendgo.io/ko/sdk/java.md): Java에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 순수 Java SDK
- [Ruby (sendgo)](https://sendgo.io/ko/sdk/ruby.md): Ruby에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Ruby SDK
- [.NET (Sendgo.SDK)](https://sendgo.io/ko/sdk/dotnet.md): .NET / ASP.NET Core에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 .NET SDK

### 프레임워크 확장

- [Laravel (sendgo/laravel)](https://sendgo.io/ko/sdk/laravel.md): Laravel에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Laravel 패키지
- [Symfony (sendgo/symfony)](https://sendgo.io/ko/sdk/symfony.md): Symfony에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Symfony 번들
- [WordPress (sendgo/wordpress)](https://sendgo.io/ko/sdk/wordpress.md): 카카오 알림톡·브랜드메시지와 SMS/LMS/MMS 를 발송하고, WooCommerce 주문 상태에 따라 구매자에게 자동으로 알리는 공식 WordPress 플러그인
- [NestJS (@sendgo/nestjs)](https://sendgo.io/ko/sdk/nestjs.md): NestJS에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 NestJS 모듈
- [Django (sendgo-django)](https://sendgo.io/ko/sdk/django.md): Django에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Django 확장 패키지
- [FastAPI (sendgo-fastapi)](https://sendgo.io/ko/sdk/fastapi.md): FastAPI에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 FastAPI 확장 패키지
- [Spring Boot (io.sendgo:sendgo-spring)](https://sendgo.io/ko/sdk/spring.md): Spring Boot에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Spring Boot Starter
- [Ruby on Rails (sendgo-rails)](https://sendgo.io/ko/sdk/rails.md): Rails에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 Rails 확장 젬
- [ASP.NET Core (Sendgo.AspNetCore)](https://sendgo.io/ko/sdk/aspnetcore.md): ASP.NET Core에서 카카오 알림톡, 브랜드메시지, SMS를 가장 쉽게 발송하는 공식 DI 확장 패키지

### 프론트엔드 · 모바일

- [React / Next.js (@sendgo/react)](https://sendgo.io/ko/sdk/react.md): React / Next.js에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 React SDK
- [Vue / Nuxt (@sendgo/vue)](https://sendgo.io/ko/sdk/vue.md): Vue.js / Nuxt 3에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 Vue SDK
- [Flutter / Dart (sendgo_flutter)](https://sendgo.io/ko/sdk/flutter.md): Flutter / Dart 서버에서 카카오 알림톡, 브랜드메시지, SMS를 발송하는 공식 Dart SDK

### 레퍼런스

- [OpenAPI (send-go/openapi)](https://sendgo.io/ko/sdk/openapi.md): Sendgo API의 OpenAPI 3.0.3 스펙입니다. 코드 생성기, API 클라이언트, AI 코딩 도구에

## 샌드고 쿡북 — 카카오 알림톡·문자 발송 예제

### 시작하기

- [5분 만에 카카오 알림톡 발송하기 — 샌드고 빠른 시작](https://sendgo.io/ko/cookbook/quickstart.md): 액세스 키 발급부터 첫 카카오 알림톡 발송까지, PHP · Node.js · Python · Java · Go 코드로 5분 안에 끝내는 방법.
- [알림톡·브랜드메시지·문자 중 뭘 써야 하나 — 채널 선택 가이드](https://sendgo.io/ko/cookbook/choose-channel.md): 카카오 알림톡, 브랜드메시지, SMS/LMS/MMS 는 각각 보낼 수 있는 내용과 비용, 사전 준비가 다릅니다. 상황별로 어느 채널을 골라야 하는지 정리했습니다.
- [카카오 알림톡 SDK 고르기 — 언어·프레임워크별 공식 패키지](https://sendgo.io/ko/cookbook/choose-sdk.md): PHP, Laravel, Node.js, Next.js, Python, Django, FastAPI, Java, Spring, Go, Ruby, Rails, .NET, Flutter, WordPress 중 어떤 샌드고 패키지를 설치해야 하는지 한 표로 정리했습니다.
- [샌드고 API 인증 — 액세스 키와 Bearer 토큰](https://sendgo.io/ko/cookbook/authentication.md): accessKey/secretKey 로 토큰을 발급받아 Bearer 인증으로 호출하는 방법. v1 과 v2 의 차이, 토큰 캐싱, 401/403 처리까지.
- [발신번호 사전등록 — 문자·알림톡 발송 전 필수 절차](https://sendgo.io/ko/cookbook/sender-number.md): 전기통신사업법상 사전등록된 번호로만 발송할 수 있습니다. 발신번호 등록과 카카오 발신프로필 연결 절차, 자주 막히는 지점을 정리했습니다.

### 메시지 보내기

- [카카오 알림톡 보내기 — PHP · Node.js · Python · Java · Go 예제](https://sendgo.io/ko/cookbook/send-alimtalk.md): 승인된 템플릿 코드로 카카오 알림톡을 발송하는 코드. Laravel, Node.js, Python, PHP, Java, Go, Ruby, .NET 예제와 필수 파라미터, 실패 원인을 정리했습니다.
- [SMS · LMS · MMS 문자 보내기 — 언어별 예제](https://sendgo.io/ko/cookbook/send-sms.md): 샌드고로 SMS(90바이트), LMS(장문), MMS(이미지)를 발송하는 방법. 타입 선택 기준, 바이트 계산, 광고 문자 규칙까지 정리했습니다.
- [카카오 브랜드메시지 보내기 — 친구톡 후속 채널](https://sendgo.io/ko/cookbook/send-brand-message.md): 브랜드메시지로 채널 친구·비친구·전체 동보 발송하는 방법. targeting 값에 따른 경로 차이와 친구톡 API 를 계속 써야 하는 예외까지.
- [알림톡 실패 시 SMS 대체 발송 설정하기](https://sendgo.io/ko/cookbook/sms-fallback.md): replaceSms 로 카카오 알림톡이 도달하지 못했을 때 자동으로 문자를 보내는 방법. 필수 파라미터와 흔한 실수를 정리했습니다.
- [알림톡 대량 발송과 치환 변수 — 수신자마다 다른 내용 보내기](https://sendgo.io/ko/cookbook/bulk-send.md): contacts 배열로 수신자별 변수를 채워 한 번에 발송하는 방법. 배치 크기, 부분 실패 처리, 큐 사용 패턴까지.
- [알림톡·문자 예약 발송하기 — scheduleType 과 at](https://sendgo.io/ko/cookbook/scheduled-send.md): 지정한 시각에 카카오 알림톡이나 문자를 발송하는 방법. 예약 시각 형식, 시간대, 야간 광고 제한과의 관계를 정리했습니다.

### 운영하기

- [알림톡 템플릿 등록과 심사 통과하기 — 반려 사유와 대응](https://sendgo.io/ko/cookbook/alimtalk-template.md): 카카오 알림톡 템플릿을 등록하고 심사를 통과하는 방법. 정보성/광고성 구분, 변수 사용법, 자주 반려되는 문안과 고치는 방법.
- [샌드고 API 오류 코드와 재시도 전략](https://sendgo.io/ko/cookbook/error-handling.md): 알림톡·문자 발송 실패 시 나오는 오류 코드 전체 목록과, 재시도해도 되는 실패와 그렇지 않은 실패를 구분하는 방법.
- [문자·알림톡에 짧은주소 넣고 클릭 추적하기](https://sendgo.io/ko/cookbook/short-url.md): 샌드고 짧은 URL 로 긴 링크를 줄이고, 누가 언제 눌렀는지 통계를 확인하는 방법. 문자 바이트 절약과 반응 측정.

### 정책과 마이그레이션

- [광고성 문자·메시지 규칙 — (광고) 표기, 수신거부, 야간 발송 금지](https://sendgo.io/ko/cookbook/ad-message-rules.md): 정보통신망법상 광고성 메시지에 지켜야 하는 규칙과 코드에서 강제하는 방법. 21시~08시 발송 금지, 무료 수신거부, 사전 동의.
- [카카오 친구톡 종료(2025-12-31) 대응 — 브랜드메시지 마이그레이션](https://sendgo.io/ko/cookbook/friendtalk-sunset.md): 친구톡이 종료된 뒤 기존 코드는 어떻게 되는지, 언제 브랜드메시지로 옮겨야 하는지, 친구톡 엔드포인트를 계속 써야 하는 예외는 무엇인지.

## API 레퍼런스

- [OpenAPI 3.0.3 spec](https://sendgo.io/openapi.yaml): 전체 REST API의 기계 판독용 스펙
- [Integration overview](https://sendgo.io/applications/overview): 연동 준비물·키 발급·인증·첫 발송을 순서대로 정리한 시작 문서
- [REST API v2 guide](https://sendgo.io/applications/guide/v2): 인증, 크레딧, 발송, 발신프로필 엔드포인트 안내

## 기타

- [모든 SDK 가이드 전문](https://sendgo.io/ko/llms-full.txt)
- [AI 코딩 어시스턴트에 샌드고 연결하기](https://sendgo.io/ko/ai)
- [사이트 이용 약관](https://sendgo.io/terms-of-service)
- [개인정보 보호 방침](https://sendgo.io/privacy-policy)