PushizoDocs
Messaging & campaigns

Sending notifications

POST /v1/notifications — targeting, multi-language content, channel-specific fields, scheduling and time zones, delivery policies (TTL, priority, frequency, quiet hours), idempotency, and querying status and deliveries.

One-off messages (transactional or bulk) are created with POST /v1/notifications. The response is 202 with { id, status, recipients_estimate, external_id_missing }; delivery is asynchronous, and results show up in the counters, the Message Tracking screen and webhooks. All fields with examples in 8 languages: API → Notifications. For recurring/scheduled bulk sends, see campaigns.

POST /v1/notifications
{
  "app_id": "app_…",
  "idempotency_key": "order-1001",
  "target": { "include_external_ids": ["user_42"], "channels": ["ios_push", "android_push", "web_push"] },
  "headings": { "tr": "Siparişiniz yola çıktı", "en": "Your order has shipped" },
  "contents": { "tr": "Takip bağlantısı içeride", "en": "Tracking link inside" },
  "url": "https://pushizo.com/orders/1001",
  "data": { "order_id": "1001" },
  "send_after": "2026-10-18T09:00:00Z",
  "delayed_option": "timezone",
  "delivery_time_of_day": "09:00"
}

Targeting (target)

FieldDescription
all: trueAll active subscriptions
include_subscription_idsSpecific subscriptions (≤ 2000)
include_external_idsA list of external_ids (≤ 2000); those not found are returned in external_id_missing
include_aliases{ "external_id": [...], "crm_id": [...] } — by alias label
included_segments / excluded_segmentsSegment IDs (≤ 50)
filtersAn inline segment condition
channelsios_push, android_push, hms_push, web_push, email, sms, whatsapp, rcs; inferred from the content if omitted
test_devices_onlyTest devices only
email_to, include_phone_numbersDirectly to addresses/numbers without a subscription (an anonymous user is created)

To get the recipient count without sending: POST /v1/notifications/estimate { target, include_unsubscribed? }. An empty target returns 422 HS_NO_RECIPIENTS; an unconfigured channel returns 422 HS_CHANNEL_NOT_CONFIGURED.

Content

  • Multi-language text: headings, contents and subtitle are language maps ({ "tr": …, "en": … }); if the recipient's language is missing, en is used, and if that is missing too, the first language.
  • Liquid: all text fields are personalized: {{ user.tags.name }}, {{ user.properties.city }}, {{ subscription.language }}, {{ event.properties.* }} (in journeys), and Data Feeds and Content Tables variables. Liquid is sandboxed; no file/network access.
  • Template: use a versioned template with template_id; fields in the body override the template.
  • Click: url (web/browser), app_url (deep link), buttons / web_buttons (action buttons), data (custom payload).
  • Channel fields: iOS (ios_sound, ios_badge_type, ios_interruption_level, ios_attachments, thread_id…), Android (android_channel_id, small_icon, big_picture…), Web (chrome_web_icon, chrome_web_image, require_interaction…), email (email_subject, email_mjml/email_body, email_preheader…), SMS (sms_from, sms_media_urls), WhatsApp (whatsapp_template, whatsapp_media, whatsapp_interactive), RCS (rcs_card, rcs_suggestions, rcs_fallback_text). Details: the relevant channel pages.
  • Notification inbox: add_to_inbox, inbox_ttl (inbox).
  • Meta: name (name shown in the dashboard), labels (filtering), category (preference category).

Violations of content rules (length, URL scheme, Liquid syntax, 4 KB push payload) return 422 HS_CONTENT_INVALID.

Scheduling

FieldBehavior
send_afterISO 8601; not sent before this time (scheduled in the queue)
delayed_option: "timezone" + delivery_time_of_day: "HH:MM"At the given time in each recipient's own time zone; if that time has passed, the next day
delayed_option: "optimized"At the most frequent hour in the recipient's 30-day open-time histogram (Intelligent Delivery); the app default if there is no data
ttlHow long the provider holds the message, in seconds (60–2,419,200)
priority10 high (wake immediately), 5 normal
collapse_idReplaces the previous notification with the same ID

A scheduled/queued message is cancelled with DELETE /v1/notifications/{id}; a message whose sending has started cannot be cancelled.

Delivery policies

Rules defined in the app settings (Settings → Delivery policies) apply to every send:

  • Frequency cap: per-user window(s) (e.g. 3 per day, 10 per week); frequency_cap_exempt: true exempts a transactional message.
  • Quiet hours: push is not sent during the defined range in the recipient's local time and is deferred to the end of the window; quiet_hours_exempt: true exempts it.
  • One per user: with one_per_user: true, only one delivery goes to a user with multiple devices.
  • Rate limit: at most N deliveries per minute with throttle_rate_per_minute (to protect the provider or your own backend).
  • Category/preference: a message with a category is suppressed according to the user's preference for that category/channel.
  • Suppression list, subscription status and channel status are always applied.

Suppressed deliveries are recorded with status suppressed and a suppression_reason, and appear in the counts.suppressed counter: frequency_cap, category_opt_out (preference), suppression_list, no_opt_in, channel_inactive, invalid_address, whatsapp_window_closed (24-hour window), holdout (A/B control group).

Idempotency

The Idempotency-Key header or idempotency_key in the body: the same key + same body returns the same response for 24 hours; a different body returns 409 HS_IDEMPOTENCY_CONFLICT, and a request still in progress returns 409 HS_IDEMPOTENCY_IN_PROGRESS. If no key is given, the server SDKs generate a UUID automatically and reuse it on retries. Details: idempotency.

Status and deliveries

  • GET /v1/notifications/{id} → status (queued, processing, completed, cancelled, failed) and counts (targeted, suppressed, sent, delivered, failed, errored, expired, opened, clicked, converted, bounced, complained, unsubscribed, sms_segments).
  • GET /v1/notifications/{id}/deliveries?status=&cursor= → per-subscription deliveries (queued → sent → delivered/received → opened/clicked, failed + error_code).
  • GET /v1/notifications/{id}/history → delivery CSV job; POST …/export_events → event CSV job (download_url once complete).
  • GET /v1/notifications?app_id=&source=&status=&label=&cursor= → message list (source: api, campaign, journey, test).

The delivery timeline and provider responses are in the dashboard under Message Tracking; transient delivery errors are retried on a 30 s / 2 min / 10 min / 30 min / 2 h schedule, and an invalid token marks the subscription invalid.

On this page