# 메시징 API v2 개요

메시징 API v2는 Pushwoosh가 지원하는 모든 채널에서 아웃바운드 메시지를 생성하기 위한 단일 REST/JSON 엔드포인트입니다:

- 푸시: iOS, Android, Huawei, Baidu, macOS, Amazon, Windows, Safari, Chrome, Firefox, IE
- 이메일
- SMS
- Telegram, Kakao, LINE, WhatsApp, Viber

**채널**은 페이로드 유형(`payload`는 푸시 / SMS / 메신저용, `email_payload`는 이메일용)에 따라 선택됩니다.

**타겟팅**은 요청 종류(`segment`는 오디언스 세그먼트용, `transactional`은 명시적인 디바이스 또는 사용자 목록용)에 따라 선택됩니다.

## 기본 URL

```
https://api.pushwoosh.com
```

전용 리전이나 프라이빗 배포를 사용하는 경우, Pushwoosh 고객 성공 관리자에게 정확한 기본 URL을 확인하십시오.

## 인증

모든 요청에는 서버 측 Pushwoosh [API 액세스 토큰](/ko/developer/api-reference/api-access-token/#server-api-token)이 포함된 `Authorization` 헤더가 있어야 합니다:

```
Authorization: Token YOUR_API_TOKEN
```

서버 간 API 호출에 이미 발급한 동일한 토큰을 사용하십시오. 이 토큰을 클라이언트 애플리케이션에 노출하지 마십시오.

## 메서드

- [`Notify`](/ko/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. 단일 메시지(세그먼트 또는 트랜잭션)를 생성하고 보냅니다.
- [`Cancel`](/ko/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. 아직 전달되지 않은 이전에 생성된 메시지를 취소합니다.
- [`Update`](/ko/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. 아직 예약된 메시지를 새로운 정의로 교체합니다.

## 요청 및 응답 형식

- 콘텐츠 유형: `application/json`.
- 필드 이름은 `snake_case`를 사용합니다. `oneof` 그룹은 정확히 하나의 키가 설정된 중첩된 객체로 나타납니다.
- Enum 값은 문자열 이름으로 직렬화됩니다 (예: `"IOS"`, `"MESSAGE_TYPE_MARKETING"`).
- 성공적인 응답은 JSON 본문과 함께 HTTP 200을 반환합니다. 오류는 표준 gRPC-Gateway 오류 봉투를 사용합니다 — `{ "code": ..., "message": ..., "details": [...] }`.

## 빠른 시작

```bash title="세그먼트에 푸시 보내기"
curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "segment": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "code": "active_users",
      "payload": {
        "content": {
          "localized_content": {
            "en": {
              "ios":     { "body": "Hello from v2!" },
              "android": { "body": "Hello from v2!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'
```

## SMTP를 통한 이메일 전송

서비스가 이미 SMTP를 지원하는 경우, `Notify`를 직접 호출하는 대신 [SMTP 게이트웨이](/ko/developer/api-reference/smtp-gateway/)를 통해 트랜잭션 이메일을 제출할 수 있습니다. 게이트웨이는 각 메시지를 트랜잭션 `Notify`로 이 API에 전달하므로 동일한 인증 및 이메일 페이로드 규칙이 적용됩니다.

## 다음 단계

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="페이로드 참조" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="이메일 페이로드 참조" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="SMTP 게이트웨이" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="v1에서 마이그레이션" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>