PushizoDocs
Messaging & campaigns

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.

A campaign is a message sent to a saved audience (segments/filter) on a schedule or on a recurring basis; what sets it apart from one-off API messages (sending notifications) is its lifecycle, approval flow, A/B testing and rich statistics. In the dashboard, Messages → Campaigns offers a 5-step builder (audience → content → channels → delivery → summary).

Types and states

typeDescription
one_timeSent immediately (send)
scheduledSent at scheduled_at (schedule)
recurringrecurrence.cron (5 fields) + timezone + optional until; a new message on every trigger
automated, transactionalSystem campaigns created by journeys and the API (read-only)

State machine: draft → scheduled → running → completed; intermediate states are paused (pause/resume), cancelled, failed, and pending_approval while awaiting approval. State transitions emit the campaign.scheduled, campaign.started and campaign.completed webhooks.

Definition

{
  "name": "Spring campaign",
  "type": "scheduled",
  "audience": { "included_segments": ["seg_…"], "excluded_segments": [], "channels": ["ios_push", "android_push", "email"] },
  "content": { "headings": { "tr": "Bahar indirimi" }, "contents": { "tr": "Seçili ürünlerde %20" }, "email_subject": "Bahar indirimi başladı", "template_id": "tpl_…" },
  "delivery": {
    "timezone_mode": "per_user_timezone",
    "delivery_time_of_day": "10:00",
    "throttle_per_minute": 5000,
    "ttl": 86400,
    "priority": 10,
    "frequency_cap_exempt": false,
    "quiet_hours_exempt": false,
    "one_per_user": true
  },
  "send_at": "2026-10-20T07:00:00Z",
  "variants": [
    { "name": "A", "weight_percent": 45, "content": null },
    { "name": "B", "weight_percent": 45, "content": { "headings": { "tr": "Bugüne özel %20" } } },
    { "name": "Holdout", "weight_percent": 10, "is_control": true }
  ],
  "ab_test": { "enabled": true, "test_percentage": 20, "winner": { "mode": "auto", "metric": "click_rate", "evaluate_after_minutes": 120 } }
}
  • Audience: segments, a filter AST and channels; if no channels are given, they are inferred from the content.
  • Content: inline content or template_id (+ template_version); labels and category (preferences).
  • Delivery: timezone_mode (immediate, per_user_timezone, optimized), time of day, rate limit, TTL, priority, collapse_id, frequency cap/quiet hours exemptions, one_per_user.
  • A/B: variants (null content → campaign content; is_control for a holdout) and ab_test (test percentage, manual/automatic winner, metric, evaluation period); deterministic assignment and z-test significance (A/B testing).

Approval flow

When the app setting campaignApprovalRequired is on, the marketer role cannot send; a send/schedule request moves to pending_approval, and approval.pending_action shows who needs to approve. POST …/campaigns/{id}/approve (admin/owner) approves it; the approval screen shows a quota preview (impact on message/subscriber quotas). If the campaign is edited the approval is kept, but if the content changes it must be approved again.

Public API

OperationEndpoint
List / createGET, POST /v1/apps/{app_id}/campaigns
Read / update / deleteGET, PATCH, DELETE …/campaigns/{id} (PATCH changes only the fields you send)
LifecyclePOST …/{id}/send, /schedule { scheduled_at?, recurrence? }, /pause, /resume, /cancel, /approve, /duplicate, /resend-failed
StatisticsGET …/{id}/stats (counters, rates, error codes), GET …/{id}/variants/stats, GET …/{id}/messages, GET …/{id}/deliveries
A/B winnerPOST …/{id}/winner { variant_id }

Reading requires analytics:read, writing requires admin. All fields and examples: API → Campaigns. In the server SDKs, use hs.campaigns.*.

Statistics and monitoring

stats returns: targeted, suppressed, sent, delivered, failed, opened, clicked, converted, bounced, complained, unsubscribed; rates (delivery_rate, open_rate, click_rate, conversion_rate); breakdowns by channel and day; and the distribution of error codes. An hourly delivery_event_rollups job updates the report tables; conversions are counted according to is_conversion in the event definition and the attribution window (analytics).

For recurring campaigns, every trigger creates a separate message (msg_…); GET …/{id}/messages lists them. Pending deliveries of a paused campaign are deferred and continue when it is resumed; cancelling drops the pending ones.

On this page