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
type | Description |
|---|---|
one_time | Sent immediately (send) |
scheduled | Sent at scheduled_at (schedule) |
recurring | recurrence.cron (5 fields) + timezone + optional until; a new message on every trigger |
automated, transactional | System 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
contentortemplate_id(+template_version);labelsandcategory(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(nullcontent → campaign content;is_controlfor a holdout) andab_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
| Operation | Endpoint |
|---|---|
| List / create | GET, POST /v1/apps/{app_id}/campaigns |
| Read / update / delete | GET, PATCH, DELETE …/campaigns/{id} (PATCH changes only the fields you send) |
| Lifecycle | POST …/{id}/send, /schedule { scheduled_at?, recurrence? }, /pause, /resume, /cancel, /approve, /duplicate, /resend-failed |
| Statistics | GET …/{id}/stats (counters, rates, error codes), GET …/{id}/variants/stats, GET …/{id}/messages, GET …/{id}/deliveries |
| A/B winner | POST …/{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.
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.
Pre-send check
Before a campaign is sent or scheduled its content is checked automatically: brand guide, banned phrases and phishing, links, personalization (Liquid) errors and KVKK/İYS rules. Available on every plan…