> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/concepts/campaigns.md). # Campaigns One send of one template to one audience — split into batches and tracked message by message. The same feature for Email, SMS and Push. > A **campaign** is one send of one [message template](/codemash/cloud/concepts/message-templates.md) to one audience, through one [integration](/codemash/cloud/concepts/integrations.md). Norbix splits it into batches and keeps a record of every batch and every message. ## What it is Sending the same message to many people from your own code means loops, retries, rate limits and a log of who got what. A campaign does that for you. Campaigns are one cross-cutting feature with three channels — **Email**, **SMS** and **Push**. The channels share the audience types, the batches, the statuses, the create rules and the ways a campaign starts; each channel adds its own recipients and options. ## The parts * **Template** — what is sent. A campaign points at a template by id (`tmpl_…`). See [Message templates](/codemash/cloud/concepts/message-templates.md). * **Provider** — the [integration](/codemash/cloud/concepts/integrations.md) that delivers it. Every campaign stores the id of its provider. * **Audience** (delivery settings) — who receives it. Every channel has the same four audience types plus one of its own: | Audience | `recipientsSourceType` | Email | SMS | Push | | --------------------------------------- | ------------------------------------ | :-------------: | :-----------: | :-----: | | All users (optionally narrowed by role) | `allUsers` | yes | yes | yes | | Account owner or team members | `accountUsers` | yes | yes | yes | | Specific users | `specifiedUsers` | yes | yes | yes | | Recipients from a collection | `collection` | yes | yes | yes | | Raw addresses / numbers / devices | `email` / `phoneNumbers` / `devices` | email addresses | phone numbers | devices | * **Language** — an optional forced language; else each recipient's language when it is a project language; else the project default. See [Which language a message is sent in](/codemash/cloud/concepts/message-templates.md#which-language-a-message-is-sent-in). * **On behalf of** — an optional project user who fills the `Initiator.User.*` tokens. When nobody is picked, the caller (the person who pressed **Send**, the task's initiator user, or the user who saved the trigger) stands in. * **Token values** — values for your own tokens in the template. See [the token rule](/codemash/cloud/concepts/message-templates.md#the-token-rule). * **Batches and messages** — the recipients are split into batches; each batch and each message has its own state, shown on the campaign's details page and in its message log. ### The four ways a campaign starts | How | Who | Where | | ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | **Send now** | a person, or your code | the channel's campaign form, or the Create … Campaign endpoint | | **Send later** | a person, or your code | the same form with a date, time and time zone: the campaign waits as **Scheduled** and starts by itself at that time | | **Scheduler task** | a [scheduled task](/codemash/cloud/tasks.md) | the task holds the campaign and a cron schedule; every time the schedule fires, it starts a new campaign — Email, SMS or Push | | **Trigger action** | a [trigger](/codemash/cloud/concepts/triggers.md) | an Email, SMS or Push action starts a campaign each time its event fires | Scheduler tasks and triggers **start** campaigns; they do not own them. Every campaign — whoever started it — appears in its channel's campaign list. ### Statuses | Status | Meaning | | ---------------------------- | ---------------------------------------------------------------------------------- | | **Pending** / **Registered** | Created, not yet picked up for sending | | **Scheduled** | Waiting for the date and time picked with **Send later**; it starts by itself then | | **Started** / **Processing** | Batches are being sent | | **Completed** | Every batch is done | | **Stopped** | Stopped by a person, or because the channel module was turned off | | **Failed** | It could not run — the errors are on its details page | **Completed**, **Stopped** and **Failed** are final. A stopped campaign is not resumed. ## Rules that are the same everywhere * **Checked before anything is stored.** A new campaign — made by hand, by a task or by a trigger — is refused, and nothing is stored, when: it has no provider (`CM-ERRORS-INTEGRATIONS-003`); the provider does not exist in this environment (`CM-ERRORS-INTEGRATIONS-001`) or is disabled (`CM-ERRORS-INTEGRATIONS-005`); the forced language is not a project language (`CM-ERRORS-LANGUAGES-003`); the template misses a translation for a project language (`CM-ERRORS-LANGUAGES-004`); or the picked "on behalf of" user does not exist. * **The server never picks the provider for you.** The portal pre-selects the default provider of the environment; the request itself must name one. * **Checked again before sending.** Project settings or the provider can change after the create. If, when the campaign starts, the provider was disabled or a project language was added that the template does not have, the campaign ends **Failed** with that error and nothing is sent. * **Send later is one time in one zone.** A scheduled campaign goes out at the same moment for everyone — the time you picked, read in the time zone you picked. Stop it before then and it is never sent. Repeating sends belong in a [scheduler task](/codemash/cloud/tasks.md). * **Stop.** Each channel has a Stop endpoint and a **Stop campaign** action. Stopping is not undoing: what was already handed to the provider is not called back. * **Turning the channel off stops every campaign.** When Email, SMS or Push is turned off in its settings, every scheduled or running campaign of that channel becomes **Stopped**. * **A campaign cannot be edited.** To send it again with changes, open it and use **Create new from this**. * **Campaigns live in the project's own database.** While that database is still being set up, the campaign lists stay empty. ## Where it lives | Channel | Portal page | SDK methods | API reference | | ------- | -------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | Email | [Email → Campaigns](/codemash/cloud/emails/campaigns.md) | [Email](/codemash/sdks/notifications/email.md) | [Email](/codemash/api-reference/notifications/email.md) · [Email messages](/codemash/api-reference/notifications/emails.md) | | SMS | [SMS → Campaigns](/codemash/cloud/sms/campaigns.md) | [SMS](/codemash/sdks/notifications/sms.md) | [SMS](/codemash/api-reference/notifications/sms.md) | | Push | [Push → Campaigns](/codemash/cloud/push/campaigns.md) | [Push](/codemash/sdks/notifications/push.md) | [Push](/codemash/api-reference/notifications/push.md) | Each channel has the same endpoints: list, get, create, stop, delete, statistics, batches, the messages of one batch, one message, and the campaign's message log. ## What is different per module | Channel | Own audience | Own options and rules | | ------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Email | email addresses | **Single email strategy** (one email per "To:" recipient), CC and BCC. Campaigns to raw addresses get no unsubscribe links. | | SMS | phone numbers | The sender (number or sender ID) belongs to the integration. | | Push | devices | An audience-count endpoint (`POST …/push/campaigns/audience-count`). Recipients with no registered device cannot be reached and are not counted as failures. | ## Related * [Message templates](/codemash/cloud/concepts/message-templates.md) — what a campaign sends * [Integrations](/codemash/cloud/concepts/integrations.md) — the provider a campaign sends through * [Triggers](/codemash/cloud/concepts/triggers.md) — start a campaign when an event happens * [Tasks (Scheduler)](/codemash/cloud/tasks.md) — start a campaign on a cron schedule * [Notification preview link](/codemash/cloud/concepts/message-templates/preview-link.md) — open one sent message