샌드고 연동에서 코드는 마지막 한 단계고, 그 앞에는 계정 설정이 있습니다. 조직을 고르고, 키를 받고, 발신번호와 템플릿을 등록하는 일 — 지금까지는 이 전부가 브라우저에서 클릭해야 하는 작업이었습니다.

이제는 아닙니다. **충전을 제외한 모든 작업**이 API 이고, 코딩 에이전트가 직접 호출할 수 있습니다.

> 딱 한 번만 사람이 합니다: 콘솔에서 에이전트 토큰을 발급해 환경변수로 넘기는 것. 애플리케이션 키는 자기 자신을 만들 수 없으므로 이 단계는 없앨 수 없습니다.

## 1단계 — 에이전트 토큰 발급 (유일한 수동 단계)

[샌드고 콘솔](https://sendgo.io)에 로그인해 **연동 관리 → AI 에이전트 토큰**으로 갑니다. 이름과 권한 범위를 고르면 토큰이 한 번 표시됩니다.

권한 범위는 여섯 개입니다.

| 범위 | 할 수 있는 일 |
| --- | --- |
| `account:read` | 조직, 키 목록, 발신번호, 템플릿, 잔액 조회 |
| `keys:write` | 애플리케이션 키 발급·폐기, 허용 IP 관리 |
| `senders:write` | 문자 발신번호 등록, 카카오 채널 연동 |
| `templates:write` | 알림톡·브랜드메시지·문자 템플릿 등록, 검수 요청 |
| `ops:write` | 웹훅 구독, 짧은 URL, 이미지 업로드 |
| `messages:send` | 실제 발송 (크레딧 차감) |

기본값은 **`messages:send` 를 뺀 나머지 전부**입니다. 셋업은 에이전트에게 맡기고 발송은 사람이 한 번 더 확인하는 구성이 가장 흔하기 때문입니다.

받은 값을 환경변수에 둡니다. 저장소에 커밋하지 마세요.

```sh
export SENDGO_AGENT_TOKEN="여기에-발급받은-토큰"
```

## 2단계 — MCP 서버 등록

MCP(Model Context Protocol)를 지원하는 에이전트라면 주소 하나만 등록하면 끝입니다.

Claude Code:

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

Cursor · Windsurf · 그 밖의 MCP 클라이언트는 설정 파일에 같은 내용을 씁니다.

```json
{
  "mcpServers": {
    "sendgo": {
      "type": "http",
      "url": "https://sendgo.io/mcp",
      "headers": {
        "Authorization": "Bearer ${SENDGO_AGENT_TOKEN}"
      }
    }
  }
}
```

등록하면 두 가지가 함께 들어옵니다.

- **도구** — 공개 API 의 모든 엔드포인트. 도구 목록은 `openapi.yaml` 에서 생성되므로 스펙과 어긋날 수 없습니다. 토큰에 없는 범위의 도구는 목록에 나타나지 않습니다.
- **리소스** — SDK 가이드 20종과 이 쿡북 전체, 그리고 에이전트 규칙 파일(`sendgo://rules`). 에이전트가 언어별 관용구를 웹에서 찾지 않고 여기서 읽습니다.

MCP 를 쓰지 않는다면 [3단계의 REST 호출](#3단계-조직-선택과-키-발급)을 그대로 쓰면 됩니다.

## 3단계 — 조직 선택과 키 발급

에이전트에게 시킬 첫 호출은 **현재 상태 확인**입니다.

```sh
curl -s https://sendgo.io/api/v2/account \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN"
```

MCP 에서는 `get_account` 도구입니다. 응답의 `nextSteps` 에 지금 막혀 있는 것이 문장으로 들어 있습니다 — 기업 승인 대기, 키 승인 대기, 토큰 범위 부족처럼 코드로 풀 수 없는 이유들입니다. 에이전트는 이 문장을 사용자에게 그대로 전달하면 됩니다.

조직 목록을 읽고 고릅니다.

```sh
curl -s https://sendgo.io/api/v2/account/organizations \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN"

curl -s -X POST https://sendgo.io/api/v2/account/organizations/select \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"organizationId":"조직-uuid"}'
```

> **카카오는 기업 조직만 됩니다.** 알림톡·브랜드메시지는 승인된 기업 소유 애플리케이션만 쓸 수 있습니다. 개인 계정으로는 문자만 보낼 수 있으므로, 조직 목록의 `kakaoAvailable` 을 먼저 확인하세요.

키를 발급합니다.

```sh
curl -s -X POST https://sendgo.io/api/v2/account/api-keys \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"production"}'
```

`secretKey` 전문은 **이 응답에서 한 번만** 나옵니다. 에이전트는 즉시 `.env` 에 써야 합니다.

```
SENDGO_ACCESS_KEY=...
SENDGO_SECRET_KEY=...
```

사이트 설정에 따라 발급 직후 상태가 `PENDING` 일 수 있습니다. 그 경우 운영자 승인 전까지 토큰 발급이 거부됩니다 — **발급 성공이 사용 가능을 뜻하지 않습니다.**

허용 IP 를 걸 거라면 함정이 하나 있습니다.

```sh
curl -s -X POST https://sendgo.io/api/v2/account/api-keys/{apiKeyId}/allowed-ips \
  -H "Authorization: Bearer $SENDGO_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip":"203.0.113.7","description":"production egress"}'
```

> **첫 IP 를 등록하는 순간 IP 제한이 켜집니다.** 그 전까지는 제한이 없었고, 등록 후에는 목록에 없는 모든 IP 가 `IP_NOT_ALLOWED` 로 막힙니다. 개발 노트북에서 잘 되던 호출이 배포 후 죽는 사고가 대부분 여기서 나옵니다. 조회 응답의 `callerIp` 에 지금 호출한 IP 가 들어 있으니 참고하세요.

## 4단계 — 발신번호와 템플릿 등록

발신번호는 법령상 사전등록이 필요합니다. 등록 유형과 필요한 서류를 먼저 조회합니다.

```sh
curl -s https://sendgo.io/api/v2/senders/number-types \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

이후 `POST /api/v2/senders` 로 접수합니다. 자세한 절차는 [발신번호 등록하기](/ko/cookbook/sender-number)에 있습니다.

알림톡 템플릿은 `POST /api/v2/notice-templates` 로 등록하고 `POST /api/v2/notice-templates/{templateCode}/inspection` 으로 검수를 요청합니다. 등록·수정·검수 취소까지 전부 API 입니다 — [관리 작업을 API 로 옮기기](/ko/cookbook/manage-by-api)에서 다룹니다.

> **등록은 접수이고, 승인이 아닙니다.** 발신번호는 샌드고 운영자가, 템플릿은 카카오가 심사합니다. 에이전트가 등록 직후 발송을 이어 붙이고 "완료" 라고 보고하면 틀린 보고입니다. 웹훅을 구독해 결과를 받으세요.

```sh
curl -s -X PUT https://sendgo.io/api/v2/webhook \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/sendgo","enabled":true}'
```

## 5단계 — 발송

승인이 끝나면 발송입니다. 에이전트가 코드를 쓰기 전에 자기 언어의 SDK 가이드를 읽게 하세요 — 이름 규칙이 언어마다 달라서(`templateCode` vs `template_code`) 추측하면 컴파일되지 않는 코드가 나옵니다. MCP 에서는 `sendgo://sdk/laravel` 처럼 리소스로 읽고, 아니면 `https://sendgo.io/ko/sdk/laravel.md` 를 가져오면 됩니다.

발송 자체는 [알림톡 보내기](/ko/cookbook/send-alimtalk)와 [문자 보내기](/ko/cookbook/send-sms)에 있는 코드와 같습니다.

## 에이전트에게 규칙 파일을 주기

MCP 없이도 에이전트가 올바른 코드를 쓰게 하려면, 규칙 파일을 저장소에 넣어 두는 방법이 있습니다.

```sh
curl -o AGENTS.md https://sendgo.io/sendgo-rules.md
```

Claude Code 는 `CLAUDE.md`, Cursor 는 `.cursor/rules/sendgo.mdc`, Copilot 은 `.github/copilot-instructions.md` 를 읽습니다. 파일은 카탈로그에서 생성되므로 항상 현재 상태와 일치합니다. [에이전트 연동 안내](/ko/ai)에 도구별 경로가 정리되어 있습니다.

## 안 되는 것

| 작업 | 가능 여부 |
| --- | --- |
| 조직 조회·전환 | API · MCP |
| 애플리케이션 키 발급·폐기·IP 관리 | API · MCP |
| 발신번호 등록·심사 접수 | API · MCP |
| 카카오 채널 연동·인증번호 요청 | API · MCP |
| 템플릿 등록·수정·검수 요청 | API · MCP |
| 발송, 결과 조회, 잔액 조회 | API · MCP |
| 웹훅 구독, 짧은 URL | API · MCP |
| **크레딧 충전 (결제)** | **콘솔에서만** |
| 이미지 파일 업로드 | API (multipart) — MCP 도구로는 제공하지 않습니다 |

카카오 채널 인증번호는 카카오가 채널 관리자 휴대폰으로 보내는 SMS 입니다. API 로 요청은 할 수 있지만 그 번호를 읽어 입력하는 것은 사람이어야 합니다 — 카카오가 직접 하는 확인이라 없앨 수 없습니다.