A campaign is a batch notification job. It wraps a template with a list of recipients, supports scheduling, and tracks delivery through a status lifecycle. Use campaigns when you need to send the same notification to many users with full lifecycle visibility.
What is the campaign lifecycle?
Campaigns progress through five statuses:
| Status | Description |
|---|
draft | Initial state. Add recipients and configure settings. |
scheduled | Send has been scheduled for a future time. |
sending | Delivery is in progress. |
sent | All recipients have been processed. |
failed | Delivery encountered an error. |
draft → scheduled → sending → sent
↘ sending → failed
You can only modify a campaign while it is in draft status. Once scheduled or sent, the campaign is locked.
How do I add recipients?
There are two ways to target users:
Manual — Post an array of user IDs to the add recipients endpoint.
CSV upload — Upload a CSV file with a userId column and optional variable columns via the upload endpoint. This is ideal for large recipient lists with per-user variable values.
CSV uploads support variable columns that map to the template’s variableSchema. Each row can have unique variable values for personalized delivery.
How does scheduling work?
When you call the send campaign endpoint, you can include an optional scheduledAt timestamp (ISO 8601). If provided, the campaign moves to scheduled status and delivery begins at the specified time. If omitted, delivery starts immediately.
What is the deliveryMode?
Campaigns support two delivery modes:
| Mode | Description |
|---|
realtime | Delivers notifications immediately per target |
batch | Queues notifications for bulk processing |
Realtime mode is designed for single-target sends. For campaigns with many recipients, use batch mode to avoid rate limiting.
How do campaigns differ from one-call notifications?
| Feature | Campaign | One-call notification |
|---|
| Recipients | Up to 100,000 via CSV | Up to 10,000 targets per call |
| Scheduling | Supports future scheduling | Immediate only |
| Lifecycle | Full status tracking | Fire-and-forget |
| Variable values | Per-user via CSV columns | Single set for all targets |
| Use case | Marketing, announcements | Transactional, real-time alerts |
