> For the complete documentation index, see [llms.txt](https://docs.codemash.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codemash.io/cloud/push/campaigns/new.md).

# Create a campaign

Create a push campaign — template, audience, schedule.

> Pick a template, pick who gets it, bind the tokens, and press Send — or pick a date and the same button becomes Schedule.

*Last updated 2026-09-11 · Applies to any project with the Push module enabled*

## Why it exists

Everything else in the Push module is preparation: a provider that can deliver, a template that says what to deliver, devices that can receive. This one form is where those three meet and a real send happens. It is also the screen where the order matters most — without a provider and a template there is nothing for the form to offer you.

## When you'd use it

* A launch announcement to every user with the `subscriber` role.
* A reminder to two named testers, sent through the Fake provider so nothing really leaves.
* A price-drop notice to recipients read from a `products_watchlist` collection.

## Where to find it

Push → Campaigns → **Create Campaign** · `/projects/<project>/push/campaigns/new`

Opening it from a template (**Actions → Create Campaign** in the [editor](/cloud/push/templates/editor.md)) brings you here with that template already selected.

{% hint style="info" %}
The push campaign screens are still being brought under automated test — the Playwright suite for them does not run yet, so the steps below were written from the application source rather than from a recorded test run. Tracked in testing-plan area **15-push**.
{% endhint %}

## Before you start

Requires a role that carries `…:notifications:push:campaigns:create`.

Three things must already exist, in this order:

1. A push [integration](/cloud/push/integrations.md), **set as default** for this environment — or one you will name on the template.
2. A push [template](/cloud/push/templates.md) with a body.
3. At least one registered [device](/cloud/push/devices.md) for the people you are sending to. Users with no device cannot be reached.

## Walkthrough video

A three-minute recording of the whole flow — provider, template, campaign — belongs here. The steps below are the same flow in writing; follow either.

## How to send a campaign

1. Open **Push → Campaigns → Create Campaign**. The page is titled **Add New Push Campaign**.
2. **Select template** (required) — pick your template, e.g. `Notification when user registers`. Every token found in it is listed underneath.
3. **Fill in the tokens we have found in your template** — bind each one. Reserved tokens such as `Project.Name` or `Recipient.User.FirstName` resolve by themselves; your own tokens (e.g. `@Model.ReleaseNotesUrl`) need a value here. The submit button stays disabled until all of them are bound.
4. **Select recipients** — a card picker with three sources:
   * **All users** — everyone in the project. Narrow it with **Select role(s)**, e.g. `subscriber`.
   * **Specified users** — pick people one by one, e.g. `usr_2N70JWm3JWy5cIXm9CqLYn`.
   * **Collection** — read recipients from a database collection, e.g. `products_watchlist`. Needs the Database module; if it is off the form shows an error with an **Enable** link.
5. **Advanced settings** — all optional:
   * **Save in database** — store the notification without delivering it. Useful for an in-app inbox.
   * **Respect time zone** — deliver at the chosen hour in each recipient's own local time.
   * **Send notification on behalf of** — a user picker; the message is recorded as initiated by that user rather than by you.
   * **Do not send immediately, but rather at a specific date and time** — a date-time field, e.g. `2026-09-20 09:00`.
6. Press the submit button. It reads **Send**, **Save** or **Schedule** depending on the choices above.

**What "sent" looks like:** the campaign is created with an id (`cmp_…`) and you return to the [campaigns list](/cloud/push/campaigns.md), where its status moves Registered → Processing → Completed and its batches appear on the [details page](/cloud/push/campaigns/details.md).

### Example

A release note to two testers through the Fake provider: pick template `tmpl_5Rf3EKWEKMsihdBkPAcK0`, bind its custom token `@Model.ReleaseNotesUrl` to `https://acme.dev/releases/2-4`, choose **Specified users**, add `usr_6HhkNJqLRDCJexA2Vc0oXn` and `usr_2gPFweHkeqiT3wa1AbBQfA`, leave the date empty, press **Send**.

## Good to know

* **The API has five audiences; this form offers three.** `all users`, `specified users` and `collection` are on the screen. Two more — **account users** (users at the account level rather than the project) and **devices** (raw push tokens, no user needed) — exist on the create endpoint only. Use the SDK or the API for those two.
* **Scheduling plus respect-time-zone** is a combination, not a choice: the date you pick is the hour, each recipient's own zone decides the moment.
* A scheduled campaign can be stopped before it starts; once batches are handed to the provider, stopping only affects the recipients not reached yet.
* Tokens are bound once, for the whole campaign. If you need per-person values beyond the reserved tokens, read the recipients from a collection and bind to its fields.
* The token list comes from the **saved** template. If you edit the template in another tab, reopen this form so the list matches.

## Do it in code

The `source` field is what tells the API which of the five audiences you mean.

{% tabs %}
{% tab title="JavaScript / TypeScript" %}

```ts
await norbix.hub.notifications.createPushCampaign({
  projectId: '<your-project-id>',
  campaign: {
    source: 'allUsers',
    templateId: 'tmpl_5Rf3EKWEKMsihdBkPAcK0',
    language: 'en',
    rolesNames: ['subscriber'],
  },
});
```

{% endtab %}

{% tab title="Python" %}

```python
norbix.notifications.create_push_campaign(
    projectId="<your-project-id>",
    campaign={
        "source": "specifiedUsers",
        "templateId": "tmpl_5Rf3EKWEKMsihdBkPAcK0",
        "userRecipients": ["usr_2N70JWm3JWy5cIXm9CqLYn"],
    },
)
```

{% endtab %}

{% tab title="Go" %}

```go
var out map[string]any
err := c.Hub.Notifications.CreatePushCampaign(ctx, map[string]any{
	"projectId": "<your-project-id>",
	"campaign": map[string]any{
		"source":     "devices",
		"templateId": "tmpl_5Rf3EKWEKMsihdBkPAcK0",
		"devices": []map[string]any{
			{"token": "<device-push-token>", "deliveryFamily": "Android"},
		},
	},
}, &out)
```

{% endtab %}

{% tab title=".NET" %}
Not available yet — the .NET SDK has no push client methods. Call the REST endpoint below.
{% endtab %}
{% endtabs %}

The five `source` values are `allUsers`, `specifiedUsers`, `accountUsers`, `collection` and `devices`. Each one brings its own extra fields: roles and user tags for `allUsers`, `userRecipients` for `specifiedUsers` and `accountUsers`, `schemaName` + `fields` for `collection`, and a `devices` list of token + delivery family for `devices`. Optional on all five: `integrationId`, `language`, `initiatorId`, `notes`, `mappedTokens` and `campaignTime` (a Unix timestamp in seconds — this is the schedule).

Reference: [Create Push Campaign](/sdks-and-cli/notifications/push/create-push-campaign.md) CLI: no create command; `norbix push campaigns` lists what you created.

## API reference

Endpoints: [Create Push Campaign](/api-reference/notifications/push/create-push-campaign.md), [Get Push Campaigns](/api-reference/notifications/push/get-push-campaigns.md).

## Related

[Campaigns list](/cloud/push/campaigns.md) · [Campaign details](/cloud/push/campaigns/details.md) · [Template editor](/cloud/push/templates/editor.md) · [Integrations](/cloud/push/integrations.md) · [Devices](/cloud/push/devices.md)