# Messaging API v2 overview

Messaging API v2 is a single REST/JSON endpoint for creating outbound messages across every channel Pushwoosh supports:

- Push: iOS, Android, Huawei, Baidu, macOS, Amazon, Windows, Safari, Chrome, Firefox, IE
- Email
- SMS
- Telegram, Kakao, LINE, WhatsApp, Viber

**Channel** is selected by the payload type (`payload` for push / SMS / messengers, `email_payload` for email). 

**Targeting** is selected by the request kind (`segment` for audience segments, `transactional` for explicit device or user lists).

## Base URL

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

If you use a dedicated region or private deployment, confirm the exact base URL with your Pushwoosh Customer Success Manager.

## Authentication

Every request must include an `Authorization` header with a server-side Pushwoosh [API access token](/developer/api-reference/api-access-token/#server-api-token):

```
Authorization: Token YOUR_API_TOKEN
```

Use the same token you already issue for server-to-server API calls. Do not expose this token in client applications.

## Methods

- [`Notify`](/developer/api-reference/messaging-api-v2/notify/): `POST /messaging/v2/notify`. Create and send a single message (segment or transactional).
- [`Cancel`](/developer/api-reference/messaging-api-v2/cancel/): `POST /messaging/v2/cancel`. Cancel a previously created message that has not been delivered yet.
- [`Update`](/developer/api-reference/messaging-api-v2/update/): `POST /messaging/v2/update`. Replace a still-scheduled message with a new definition.

## Request and response format

- Content type: `application/json`.
- Field names use `snake_case`. `oneof` groups appear as nested objects with exactly one key set.
- Enum values are serialized as their string names (for example, `"IOS"`, `"MESSAGE_TYPE_MARKETING"`).
- Successful responses return HTTP 200 with a JSON body; errors use the standard gRPC-Gateway error envelope — `{ "code": ..., "message": ..., "details": [...] }`.

## Quick start

```bash title="Send a push to a segment"
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"
    }
  }'
```

## Sending email over SMTP

If a service already speaks SMTP, you can submit transactional email through the [SMTP gateway](/developer/api-reference/smtp-gateway/) instead of calling `Notify` directly. The gateway forwards each message to this API as a transactional `Notify`, so the same authentication and email payload rules apply.

## Next steps

<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="Payload reference" href="/developer/api-reference/messaging-api-v2/payload-reference/" />
  <LinkCard title="Email payload reference" href="/developer/api-reference/messaging-api-v2/email-payload-reference/" />
  <LinkCard title="SMTP gateway" href="/developer/api-reference/smtp-gateway/" />
  <LinkCard title="Migration from v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>