向 AI 说明您的需求。

curl -fsSL 'https://sendgo.io/sendgo-rules.md' -o sendgo-rules.md

阅读 Sendgo 官方指南 https://sendgo.io/sendgo-rules.md。
为当前项目选择官方 SDK。
创建订单确认通知模板并提交审核。
确认批准状态后集成消息发送。
请先说明所需的账户、发送信息和 API 凭据。

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

## Do the whole setup from the agent

Picking the organisation, issuing the API key, registering the sending number and
registering the Alimtalk template are all API calls. **The only task that still
needs a browser is topping up credit.** Two surfaces, same permissions:

- **MCP server** — `https://sendgo.io/mcp`, HTTP transport. Every documented endpoint is a tool,
  and the SDK guides and recipes are exposed as MCP resources.

  ```sh
  claude mcp add --transport http sendgo https://sendgo.io/mcp \
    --header "Authorization: Bearer $SENDGO_AGENT_TOKEN"
  ```

- **Account API** — `https://sendgo.io/api/v2/account/*`, for agents without MCP.

| Purpose | Endpoint |
| --- | --- |
| Who am I, what is blocking me | `GET /api/v2/account` |
| List organisations | `GET /api/v2/account/organizations` |
| Switch organisation | `POST /api/v2/account/organizations/select` |
| Issue accessKey/secretKey | `POST /api/v2/account/api-keys` |
| Manage the IP allow-list | `POST /api/v2/account/api-keys/{id}/allowed-ips` |

Both authenticate with an **agent token**, not with `accessKey`/`secretKey` — a key
cannot create keys. A human issues the token once from the console
(https://sendgo.io/applications/agent-tokens) and exports it as `SENDGO_AGENT_TOKEN`.
Token scopes are separate: a token can be allowed to do the entire setup while
still being unable to send (`messages:send`). Ask for the scope you need; do not
assume the token has all of them.

Start every session with `GET /api/v2/account` (MCP: `get_account`). Its
`nextSteps` field says what is actually blocking progress — an unapproved
organisation, a pending key, a missing scope — so you do not guess and collect 403s.

## Rules that prevent the common failures

1. **Alimtalk needs a template that was approved first.** You can register the
   template over the API (`POST /api/v2/notice-templates`), but Kakao reviews it —
   registering is not approving. You cannot invent the text at send time; you fill
   the variables (`var1`, `var2`, …) of an approved template. A wrong or
   not-yet-approved code returns `INVALID_TEMPLATE_CODE`.
   Organise notice/brand templates with GET/POST `/api/v2/template-folders`.
   Pass the returned folderUuid when registering, or move existing templateCodes
   with PATCH `/api/v2/template-folders/templates` (templateType notice/brand,
   kakaoSenderKey, up to 100 templateCodes, explicit nullable folderUuid).
   Null means uncategorised; moving folders never changes inspection status.
2. **The sending number must be pre-registered.** Korean law (전기통신사업법) requires
   the caller ID to be verified before use. `POST /api/v2/senders` files the
   application; a Sendgo operator reviews it. An unregistered `senderKey` fails at
   send time, not at signup.
3. **Registration calls return "filed", not "usable".** Template inspection and
   sender review are asynchronous. Do not chain a send onto a registration and
   report success — subscribe to the webhook (`PUT /api/v2/webhook`) or poll the
   status endpoint, and tell the user a human review is pending.
4. **Never hard-code keys.** `accessKey`/`secretKey` come from the environment.
5. **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.
6. **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.
7. **`replaceSms: "Y"` needs `smsSubject` and `smsContent`.** Turning on SMS fallback
   without the fallback body silently sends nothing when Alimtalk fails.
8. **Handle `402 PAYMENT_REQUIRED`.** It means the credit balance ran out, not that
   the request was malformed. Retrying will not help.
9. **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
- Finish the Sendgo integration from your AI agent — MCP server and Account API — https://sendgo.io/zh/cookbook/agent-setup
- 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
- 이메일 · SMTP 연동 — 발신 인증, 뉴스레터와 자동화 수신함 — https://sendgo.io/zh/cookbook/send-email
- 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
- Doing everything over the API — operations automation for resellers — https://sendgo.io/zh/cookbook/manage-by-api
- 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