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)
| Field | Description |
|---|---|
all: true | All active subscriptions |
include_subscription_ids | Specific subscriptions (≤ 2000) |
include_external_ids | A 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_segments | Segment IDs (≤ 50) |
filters | An inline segment condition |
channels | ios_push, android_push, hms_push, web_push, email, sms, whatsapp, rcs; inferred from the content if omitted |
test_devices_only | Test devices only |
email_to, include_phone_numbers | Directly 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,contentsandsubtitleare language maps ({ "tr": …, "en": … }); if the recipient's language is missing,enis 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
| Field | Behavior |
|---|---|
send_after | ISO 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 |
ttl | How long the provider holds the message, in seconds (60–2,419,200) |
priority | 10 high (wake immediately), 5 normal |
collapse_id | Replaces 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: trueexempts 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: trueexempts 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
categoryis 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) andcounts(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_urlonce 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.
Email, SMS, in-app messages and the notification inbox
Since Phase 10, Pushizo also sends on channels beyond push: email (SMTP, Amazon SES, Resend), SMS (Twilio, Netgsm), in-app messages and the notification inbox. This document covers setup, the API contract and…
Campaigns
Campaign lifecycle — types (one-time, scheduled, recurring), state machine, audience and content, delivery settings, approval flow, A/B variants, statistics and the public API.