도구별 파일 위치

• Claude CodeCLAUDE.md

  会话开始时读取仓库根目录的 CLAUDE.md。若已存在请追加内容。

• Cursor.cursor/rules/sendgo.mdc

  放在 .cursor/rules/ 下的 .mdc 文件会作为项目规则生效。

• GitHub Copilot.github/copilot-instructions.md

  生成代码时参考仓库中的 .github/copilot-instructions.md。

• Codex / Windsurf / ClineAGENTS.md

  遵循 AGENTS.md 约定的工具共同读取的文件。

기계 판독용 진입점

에이전트가 직접 가져갈 수 있는 주소입니다. 전부 인증 없이 열려 있고 CORS 도 허용돼 있습니다.

• https://sendgo.io/llms.txt문서 지도 (llmstxt.org 규약)
• https://sendgo.io/llms-full.txt모든 SDK 가이드를 한 파일로
• https://sendgo.io/openapi.yamlOpenAPI 3.0.3 스펙
• https://sendgo.io/sendgo-rules.md이 페이지의 규칙 파일 원문

# Sendgo — rules for AI coding agents

Sendgo (https://sendgo.io) sends Kakao Alimtalk, Kakao Brand Message and
SMS/LMS/MMS in South Korea. Use an official SDK rather than hand-rolling HTTP.

Canonical docs, always current:

- Machine-readable index: https://sendgo.io/llms.txt
- Every guide in one file: https://sendgo.io/llms-full.txt
- OpenAPI 3.0.3 spec: https://sendgo.io/openapi.yaml
- Task recipes: https://sendgo.io/zh/cookbook

## Pick the package

| 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 wrap a core package — install the framework one and let it
pull the core in. Do not install both explicitly.

## API contract

- Base URL: `https://sendgo.io/api`. Version segment is `v1` or `v2`; **use `v2` for new code**.
- Auth is two steps. `POST /api/v2/token` with `Authorization: Basic base64(accessKey:secretKey)`
  returns a token; every other call sends `Authorization: Bearer <token>`.
  On v1 the bearer value is `base64(token)`; on v2 it is the raw token.
- Every SDK caches the token, refreshes it, and retries once on 401/403.
  Do not write your own token loop and do not call the token endpoint per request.

| 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` |

## Rules that prevent the common failures

1. **Alimtalk needs a template that was approved first.** `templateCode` refers to a
   template registered and approved in the Sendgo console. You cannot invent the
   text at send time; you fill the variables (`var1`, `var2`, …) of an approved
   template. A wrong code returns `INVALID_TEMPLATE_CODE`.
2. **The sending number must be pre-registered.** Korean law (전기통신사업법) requires
   the caller ID to be verified before use. An unregistered `senderKey` fails at
   send time, not at signup.
3. **Never hard-code keys.** `accessKey`/`secretKey` come from the environment.
4. **Friendtalk ended on 2025-12-31.** Do not write new code against it. Use Brand
   Message (`/api/v2/brand-messages/send`). The one exception: free-form body types
   (`FT`/`FI`/`FW`) sent to individual recipients still go through
   `/api/v2/friends/send` — the brand-message endpoint answers `NOT_A_BRAND_MESSAGE`
   for that combination.
5. **Advertising messages are regulated.** Prefix the body with `(광고)`, include an
   opt-out number, and do not send between 21:00 and 08:00 KST. Set `adFlag: "Y"`.
   Transactional Alimtalk is exempt; promotional content is not.
6. **`replaceSms: "Y"` needs `smsSubject` and `smsContent`.** Turning on SMS fallback
   without the fallback body silently sends nothing when Alimtalk fails.
7. **Handle `402 PAYMENT_REQUIRED`.** It means the credit balance ran out, not that
   the request was malformed. Retrying will not help.
8. **Phone numbers are digits only**, no hyphens: `01012345678`.

## Minimal working example

The sender keys go on the client, not on every call. Node.js
(`npm install @sendgo/node`, default export — not a named one):

```ts
import Sendgo from '@sendgo/node';

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' }],
});

await sendgo.sms.sendSms({ content: '인증번호: 123456', contacts: [{ contact: '01012345678' }] });
```

Python (`pip install sendgo-python`):

```python
from sendgo import Sendgo, SendgoError

client = Sendgo(
    access_key=os.environ["SENDGO_ACCESS_KEY"],
    secret_key=os.environ["SENDGO_SECRET_KEY"],
    kakao_sender_key=os.environ.get("SENDGO_KAKAO_SENDER_KEY"),
    sms_sender_key=os.environ.get("SENDGO_SMS_SENDER_KEY"),
    api_version="v2",
)

client.alimtalk.send(
    template_code="ORDER_CONFIRM_001",
    contacts=[{"contact": "01012345678", "name": "홍길동", "var1": "ORD-001"}],
)
```

Naming follows each language, so do not translate one SDK into another by hand:
camelCase keys in JS/PHP payloads (`templateCode`), snake_case keyword arguments in
Python and Ruby (`template_code`), builders in Java, `SendAlimtalkAsync` in .NET.
Errors surface as `SendgoError` (JS/Python), `SendgoException` (PHP), returned
`error` values in Go.

Before writing code, fetch the guide for the language you are actually in — each
one is available as raw markdown:

- PHP → https://sendgo.io/zh/sdk/php.md
- Laravel → https://sendgo.io/zh/sdk/laravel.md
- Symfony → https://sendgo.io/zh/sdk/symfony.md
- WordPress → https://sendgo.io/zh/sdk/wordpress.md
- Node.js → https://sendgo.io/zh/sdk/node.md
- React / Next.js → https://sendgo.io/zh/sdk/react.md
- Vue / Nuxt → https://sendgo.io/zh/sdk/vue.md
- NestJS → https://sendgo.io/zh/sdk/nestjs.md
- Python → https://sendgo.io/zh/sdk/python.md
- Django → https://sendgo.io/zh/sdk/django.md
- FastAPI → https://sendgo.io/zh/sdk/fastapi.md
- Go → https://sendgo.io/zh/sdk/go.md
- Java → https://sendgo.io/zh/sdk/java.md
- Spring Boot → https://sendgo.io/zh/sdk/spring.md
- Ruby → https://sendgo.io/zh/sdk/ruby.md
- Ruby on Rails → https://sendgo.io/zh/sdk/rails.md
- .NET → https://sendgo.io/zh/sdk/dotnet.md
- ASP.NET Core → https://sendgo.io/zh/sdk/aspnetcore.md
- Flutter / Dart → https://sendgo.io/zh/sdk/flutter.md
- OpenAPI → https://sendgo.io/zh/sdk/openapi.md

## Task recipes

One page per task, each also available as raw markdown at the same URL + `.md`:

- Send your first Kakao Alimtalk in 5 minutes — https://sendgo.io/zh/cookbook/quickstart
- Alimtalk, Brand Message or SMS — choosing a messaging channel in Korea — https://sendgo.io/zh/cookbook/choose-channel
- Which Sendgo SDK should I install? — 20 official packages — https://sendgo.io/zh/cookbook/choose-sdk
- Sendgo API authentication — access keys and bearer tokens — https://sendgo.io/zh/cookbook/authentication
- Registering a sending number in South Korea — required before you can send — https://sendgo.io/zh/cookbook/sender-number
- Send a Kakao Alimtalk — PHP, Node.js, Python, Java, Go examples — https://sendgo.io/zh/cookbook/send-alimtalk
- Send SMS, LMS and MMS in South Korea — code examples — https://sendgo.io/zh/cookbook/send-sms
- Send a Kakao Brand Message — the successor to Friendtalk — https://sendgo.io/zh/cookbook/send-brand-message
- SMS fallback when a Kakao Alimtalk fails — https://sendgo.io/zh/cookbook/sms-fallback
- Bulk Alimtalk sending and per-recipient variables — https://sendgo.io/zh/cookbook/bulk-send
- Scheduling an Alimtalk or SMS — scheduleType and at — https://sendgo.io/zh/cookbook/scheduled-send
- Registering an Alimtalk template and passing review — https://sendgo.io/zh/cookbook/alimtalk-template
- Sendgo API error codes and retry strategy — https://sendgo.io/zh/cookbook/error-handling
- Short links in SMS and Alimtalk, with click tracking — https://sendgo.io/zh/cookbook/short-url
- Advertising message rules in Korea — (광고) prefix, opt-out, night ban — https://sendgo.io/zh/cookbook/ad-message-rules
- Kakao Friendtalk shut down (2025-12-31) — migrating to Brand Message — https://sendgo.io/zh/cookbook/friendtalk-sunset

패키지별 원문 마크다운