> 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/sms/campaigns/new.md).

# Create a campaign and send it now

Create an SMS campaign — pick the audience, the template and the provider — and send it now.

**Where:** SMS → Campaigns → **Create Campaign** · `/projects/<project>/sms/campaigns/new`

You also land here from a template (**Actions → Create Campaign** in the [editor](/codemash/cloud/sms/templates/editor.md)) or from a campaign (**Create new from this** on its [details page](/codemash/cloud/sms/campaigns/details.md)); then the template is already picked (`…/campaigns/new?t=<template id>`).

## Before you start

* An enabled SMS [integration](/codemash/cloud/sms/integrations.md) that can send — [Twilio](/codemash/cloud/sms/integrations/providers/twilio.md) or the [Fake SMS (Test Me)](/codemash/cloud/sms/integrations/providers/fake-sms.md). Right after you enable the module the Fake is there and is the default, so nothing real is sent until you pick another one.
* An SMS [template](/codemash/cloud/sms/templates.md) with a translation for **every** project language (Project → Settings → Languages). A template that misses one is refused with `CM-ERRORS-LANGUAGES-004`; the templates list marks it **Missing …**.
* Someone to send to: users with a phone number, team members who saved their phone on **Your Profile**, or numbers you type. A recipient without a phone is skipped, not counted as failed.
* The permissions the campaign needs: `sms:create` on SMS campaigns, `project:read`, `sms:read` on the module and on the integration, and the right to read the recipients (`membership:read` for users, `account:read` for **Account users**, `database:read` for **Collection**). A missing one refuses the send with `CM-ERRORS-MEMBERSHIP-039`, and the red box on the form lists every permission you lack.

## Steps

1. Press **Create Campaign**. The form **Add New SMS Campaign** opens with **All users** selected.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-0e3776e4aa8c77a40a81ba3ec12176cff46907ad%2Fcampaigns-create-1.png?alt=media" alt="Add New SMS Campaign: five recipient cards (All users selected, Collection greyed out with This project has no collections yet., Specified Users, Phone Numbers, Account users), Select role(s), and the start of Template Details"><figcaption><p>The recipient cards.</p></figcaption></figure>
2. Under *Please choose how you would like to select your recipients.* pick one card:

   | Card                | Who gets the SMS                                                                                   | Fields                                                                                                                                 |
   | ------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
   | **All users**       | Every project user with a phone number (the profile phone, or the number the user signed up with). | **Select role(s)** — optional, e.g. `subscriber`.                                                                                      |
   | **Collection**      | The records of a database collection. Greyed out while Database is off or there is no collection.  | **Collection**, **Recipient field(s), comma separated** (e.g. `phone`), **What the field holds**: **A phone number** or **A user id**. |
   | **Specified Users** | The users you pick.                                                                                | **To:** — e.g. `Ada Lovelace`.                                                                                                         |
   | **Phone Numbers**   | The numbers you type.                                                                              | **To phone numbers (comma separated)** — international format, e.g. `+37060000001, +37060000002`.                                      |
   | **Account users**   | The account owner and team members you pick; members without a phone are skipped.                  | **Account users:**                                                                                                                     |
3. Fill **Template Details**:

   | Field                     | Required  | What it does                                                                                                                                                                                                 | Example                                |
   | ------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
   | Select template           | yes       | Opens a picker: 10 templates per page, newest first, with **Search templates by name**. Archived templates are not offered.                                                                                  | `Login code`                           |
   | Send in specific language | no        | **Each recipient's language** (default): the recipient's language when it is a project language, else the project default; typed phone numbers always get the default. Or one project language for everyone. | `Each recipient's language`            |
   | Template Tokens           | yes, each | Every `@Model.…` token the template uses. Reserved tokens fill themselves; your own tokens need a value. **Send** turns on only when every token has one and the server has rendered the text.               | `FirstName` = `Ada`, `Code` = `482913` |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-5875778b3fd109b2310dbc97ab4a50a72f4e3724%2Fcampaigns-create-4.png?alt=media" alt="Phone Numbers card with +37060000001, template Login code, Send in specific language on Each recipient&#x27;s language, and Template Tokens FirstName Ada and Code 482913"><figcaption><p>A send to one phone number with both tokens filled.</p></figcaption></figure>
4. Check **Advanced settings** (*Optional fields to customize your SMS delivery.*):

   | Field                 | Required | What it does                                                                                                                                                                        | Example                    |
   | --------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
   | Send SMS on behalf of | no       | The project user whose details fill the `@Model.Initiator.User.…` tokens. Empty = you. It is not the sender the phone shows.                                                        | `Ada Lovelace`             |
   | Select SMS provider   | yes      | The integration that sends the campaign; its number or sender ID is what recipients see. The project default is picked for you; only enabled integrations that can send are listed. | `Test Me (Fake) (Default)` |
   | When to send          | yes      | **Send now** (default) or **Send later** — see [Schedule a campaign](/codemash/cloud/sms/campaigns/schedule.md).                                                                    | `Send now`                 |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-611d4a1593e314d615064f7dfb1a9e50393c0f1b%2Fcampaigns-create-3.png?alt=media" alt="Template Details with Winter sale and Advanced settings: Send SMS on behalf of empty, Select SMS provider Test Me (Fake) (Default), and the start of When to send"><figcaption><p>Advanced settings with the default provider picked.</p></figcaption></figure>
5. Press **Send**. **Cancel** goes back to the list without creating anything.

## Result

Cloud returns to the [campaigns list](/codemash/cloud/sms/campaigns.md). The new row appears within 15 seconds and moves Registered → Processing → **Completed**; its batches, statistics and messages are on the [details page](/codemash/cloud/sms/campaigns/details.md). Through the Fake integration the messages are recorded as sent and nothing reaches a phone.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-210e4390d42ec94d5619770963dfde09c16d42e5%2Fcampaigns-create-5.png?alt=media" alt="SMS Campaigns list with the new Login code campaign Completed at the top, sent through Test Me (Default)"><figcaption><p>The campaign has completed.</p></figcaption></figure>

The provider and the languages are checked again right before the first batch: a campaign whose integration was turned off, or whose template misses a language that was added meanwhile, sends nothing and becomes **Failed** with the reason on its details page.

## Change or remove it later

* **Edit** — a campaign cannot be changed after it is created. Use **Create new from this** on its [details page](/codemash/cloud/sms/campaigns/details.md) to start a new one with the same template.
* **Stop** — a campaign that is still sending can be [stopped](/codemash/cloud/sms/campaigns/stop.md).
* **Delete** — once it is Completed, Stopped or Failed, from the **Actions** menu of its [details page](/codemash/cloud/sms/campaigns/details.md#change-or-remove-it-later).

## Do it from code

`integrationId` is required — the server never falls back to the default integration. `deliveryType` names the audience, and one block with the same name carries its fields.

```ts
const { id } = await norbix.hub.notifications.createSmsCampaign({
  templateId: 'tmpl_6ITDztVHBZQujSUOtLIZvy', // Winter sale
  integrationId: 'int_6owP11oF9ZZAt9szkqy99S', // Test Me (Fake)
  deliveryType: 'AllUsers',
  allUsers: { recipientsSourceType: 'AllUsers' },
});
console.log(id); // cmp_…
```

```sh
norbix hub notifications sms campaign create --templateId tmpl_2BHRvMydBbybNH5ThRV7fB --integrationId int_6owP11oF9ZZAt9szkqy99S --deliveryType PhoneNumbers --language en --phoneNumbers '{"recipientsSourceType":"PhoneNumbers","phoneNumbers":["+37060000001"],"mappedTokens":[{"key":"FirstName","value":"Ada","resolver":"Custom"},{"key":"Code","value":"482913","resolver":"Custom"}]}'
```

The client setup is on the [SMS page](/codemash/cloud/sms.md#use-it-from-code). API: [Create Sms Campaign](/codemash/api-reference/notifications/sms/create-sms-campaign.md)