Notify

POST https://api.pushwoosh.com/messaging/v2/notify

Creates and schedules a single message.

Request structure

The request body is a NotifyRequest with exactly one of two kinds:

• segment: target an audience segment by segment code, a seglang expression, or a structured filter expression.
• transactional: send to an explicit list of hwids, user IDs, push tokens, or test devices.

Shape

{
  "segment": { ... }       // OR
  "transactional": { ... }
}

NotifySegment

Targets users who match an audience segment or filter expression.

Field	Type	Description
schedule	Schedule	When and how to send. Required.
application	string	Application code.
platforms	array of Platform	Platforms the message targets.
code	string	Segment code. Mutually exclusive with expression and filter_expression.
expression	string	Seglang expression.
filter_expression	FilterExpression	Structured filter expression (advanced).
payload	Payload	Push / SMS / Telegram / Kakao payload. Mutually exclusive with email_payload.
email_payload	EmailPayload	Email payload.
campaign	string	Campaign code to attribute this message to.
frequency_capping	FrequencyCapping	Per-user frequency limits.
send_rate	SendRate	Throttling for the send.
message_type	MessageType	MESSAGE_TYPE_MARKETING (default) or MESSAGE_TYPE_TRANSACTIONAL. Controls control-group filtering.
dynamic_content_placeholders	map<string, string>	Replaces placeholders in content.
meta_data	object	Free-form metadata forwarded to downstream analytics.

Example: Send 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!" },
              "android": { "body": "Hello!" }
            }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_MARKETING"
    }
  }'

NotifyTransactional

Sends to an explicit list of recipients.

Field	Type	Description
schedule	Schedule	Required.
application	string	Application code.
platforms	array of Platform	Platforms the message targets.
test_devices	bool	If true, send to the app’s test devices only.
hwids	{ "list": [string, ...] }	Send to these hwids only.
users	{ "list": [string, ...] }	Send to these user IDs only.
push_tokens	{ "list": [string, ...] }	Send to these push tokens only.
payload	Payload	Push / SMS / Telegram / Kakao payload.
email_payload	EmailPayload	Email payload.
return_unknown_identifiers	bool	When true, the response’s unknown_identifiers lists identifiers that were not found.
campaign, frequency_capping, send_rate, message_type, dynamic_content_placeholders, meta_data		See NotifySegment above.

test_devices, hwids, users, and push_tokens are mutually exclusive. Exactly one must be set.

Example: Transactional by user IDs

curl -X POST https://api.pushwoosh.com/messaging/v2/notify \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional": {
      "application": "XXXXX-XXXXX",
      "platforms": ["IOS", "ANDROID"],
      "users": { "list": ["user-123", "user-456"] },
      "payload": {
        "content": {
          "localized_content": {
            "en": { "ios": { "body": "Your order has shipped." } }
          }
        }
      },
      "schedule": { "at": "2026-05-01T12:00:00Z" },
      "message_type": "MESSAGE_TYPE_TRANSACTIONAL",
      "return_unknown_identifiers": true
    }
  }'

Response

{
  "result": {
    "message_code": "XXXXX-XXXXX-XXXXX",
    "unknown_identifiers": []
  }
}

Field	Type	Description
message_code	string	Unique message code. Use it with /getMessageDetails and message statistics endpoints.
unknown_identifiers	array of string	Identifiers not found on the account. Populated only when return_unknown_identifiers: true was set on the transactional kind.

Shared types

Schedule

{
  "at": "2026-05-01T12:00:00Z",
  "follow_user_timezone": true,
  "past_timezones_behaviour": "PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY"
}

Field	Type	Description
at	timestamp	Absolute send time (RFC 3339). If in the past, the message is sent immediately. Maximum 14 days in the future.
after	duration	Alternative to at. Send after this offset from “now” (e.g. "3600s").
follow_user_timezone	bool	When true, each device receives the message at at in its local timezone.
past_timezones_behaviour	enum	PAST_TIMEZONES_BEHAVIOUR_SEND_IMMEDIATELY (default), PAST_TIMEZONES_BEHAVIOUR_DO_NOT_SEND, or PAST_TIMEZONES_BEHAVIOUR_NEXT_DAY. Only meaningful when follow_user_timezone is true.

FrequencyCapping

Per-user frequency limits for marketing sends.

{ "days": 7, "count": 3, "exclude": false, "avoid": true }

• days (int, 1–30): look-back window.
• count (int): maximum messages allowed within days.
• exclude (bool): hard-exclude users who have already hit the cap.
• avoid (bool): soft-avoid users who have already hit the cap (they still count toward analytics).

SendRate

{ "value": 500, "bucket": "1s", "avoid": false }

Throttles the send. value is messages per bucket; typical bucket is "1s".

Platform enum

IOS, ANDROID, OSX, WINDOWS, AMAZON, SAFARI, CHROME, FIREFOX, IE, EMAIL, BAIDU_ANDROID, HUAWEI_ANDROID, SMS, WEB, KAKAO, TELEGRAM, LINE, WHATS_APP.

MessageType enum

• MESSAGE_TYPE_UNSPECIFIED: equivalent to MESSAGE_TYPE_MARKETING.
• MESSAGE_TYPE_MARKETING: subject to control-group filtering and frequency capping.
• MESSAGE_TYPE_TRANSACTIONAL: skips control-group filtering and frequency capping. Use for order confirmations, OTPs, and similar critical flows.

Related

Payload reference

Email payload reference

Migration from v1