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

# Create and send now

Create an email campaign and send it now — recipients, template, tokens, provider.

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

**Add New Email Campaign** is one form: choose who gets the email, pick the template, give every token a value, check the provider, and press **Send**. You also reach this form from a template's **Actions → Create Campaign** and from a campaign's **Actions → Create new from this** — then the template is already picked.

## Before you start

* A template with a translation for **every project language** — see [Templates](/codemash/cloud/emails/templates.md). The project languages are set in [Project → Settings → Languages](/codemash/cloud/project/settings/languages.md).
* An enabled email integration. The Fake integration **Test Me** is created with the module, so you can try this without sending real mail — see [Fake Email (Test Me)](/codemash/cloud/emails/integrations/providers/fake-email.md).
* For **All users** and **Specified Users**: project users with an email address ([Membership → Users](/codemash/cloud/membership/users.md)). For **Collection**: the Database module and a collection that holds the addresses or user ids.
* Permission `email:create` (built-in **Developer** or **Administrator**). A **Viewer** can open the form, but the send is refused.

## Steps

1. Press **Create Campaign**. The form opens with the recipient cards on top.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-cdbd453370e014a1eb69a8b54baae4bcaefd76d5%2Fcampaigns-new-1.png?alt=media" alt="Add New Email Campaign form: recipient cards All users (selected), Collection, Specified Users, Email Addresses; Select role(s); Template Details"><figcaption><p>The empty form. <strong>All users</strong> is picked first.</p></figcaption></figure>
2. Pick how to choose the recipients:

   | Card                | Fields                                                                                                                          | Example                                             |
   | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
   | **All users**       | **Select role(s)** (optional) — only users with these roles                                                                     | empty = every project user with an email            |
   | **Collection**      | **Collection \***, **Recipient field(s), comma separated \***, **What the field holds** (**A user id** or **An email address**) | `subscribers`, `email`, An email address            |
   | **Specified Users** | **To: \*** (users), optional **CC:** / **BCC:**, **Single email strategy**                                                      | Ada Lovelace, Alan Turing                           |
   | **Email Addresses** | **To: \*** (comma separated), optional **CC:** / **BCC:**, **Single email strategy**                                            | `ada.lovelace@example.com, alan.turing@example.com` |

   **Single email strategy:** each "To:" recipient gets a separate email instead of one email to all of them. When the Database module is off, the **Collection** card shows **Database service is not enabled.** with an **Enable** link.
3. Under **Template Details**, open **Select template** and pick the template, for example `Welcome email (Transactional)`. Leave **Send in specific language** on **Each recipient's language** (each person gets their own language when it is a project language, else the project default), or pick one project language for everybody.
4. **Template Tokens** lists every token of the subject and the body. Give each one a value. Tokens such as `Email.SignatureId` and `Email.FooterId` take an id (`emlsgn_2zT7jxLqeylWMYCPLzDSpm`, `emlftr_3xxahehZsa7l8kj90ytaxX`). For a token Norbix fills per recipient, enter the token name itself, for example `Recipient.FirstName`. Until every token has a value, a yellow box lists the ones still missing.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-d2846c2f97a966cce61b922b365633fbe4f8cb5c%2Fcampaigns-new-2.png?alt=media" alt="Template Details with Welcome email picked, Each recipient&#x27;s language, and Template Tokens Recipient.FirstName, Email.SignatureId, Email.FooterId filled"><figcaption><p>Template picked and every token filled.</p></figcaption></figure>
5. Under **Advanced settings**, check the rest:

   | Field                   | Required | What it does                                                                                                        | Example          |
   | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | ---------------- |
   | Send email on behalf of | no       | A project user whose details fill the `@Model.Initiator.User` tokens. Empty = you.                                  | `Ada Lovelace`   |
   | Select email provider   | yes      | The integration that sends the campaign. The project default is pre-selected; only enabled integrations are listed. | `Test Me (Fake)` |
   | When to send            | yes      | **Send now** (default) or **Send later** — see [Schedule a campaign](/codemash/cloud/emails/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-53f55f40152744dfb0a10813e7d40c895eeee8e9%2Fcampaigns-new-3.png?alt=media" alt="Advanced settings: Send email on behalf of, Select email provider Test Me (Fake), When to send with Send now selected, Cancel and Send buttons"><figcaption><p>Advanced settings with the default provider and <strong>Send now</strong>.</p></figcaption></figure>
6. Press **Send**. It stays disabled until every token has a value and a provider is picked.

## Result

You are back on **Email → Campaigns**. The new campaign (`cmp_…`) appears at the top as **Registered**, moves to **Processing** and ends as **Completed** — through the Fake provider in a few seconds. Its [details](/codemash/cloud/emails/campaigns/details.md) show the batches, **Sent Emails** and the **Success rate**; the [message log](/codemash/cloud/emails/campaigns/log.md) shows each email as it was sent.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-cd4213d3af2af2f16845e4e0755bc628f6c08781%2Fcampaigns-new-4.png?alt=media" alt="Email Campaigns list with the new Welcome email campaign, status Completed, strategy All Users, integration Test Me (Default)"><figcaption><p>The campaign has finished: <strong>Completed</strong>.</p></figcaption></figure>

{% hint style="warning" %}
**Known issue:** with **All users**, the per-recipient tokens (`Recipient.FirstName` and the other `Recipient.*` tokens) render empty today — the email says "Hi," without the name. **Specified Users** with **Single email strategy** fills them.
{% endhint %}

Good to know:

* **The provider is never filled in on the server.** A request without a provider is refused (`CM-ERRORS-INTEGRATIONS-003`), an unknown one too (`CM-ERRORS-INTEGRATIONS-001`), a disabled one too (`CM-ERRORS-INTEGRATIONS-005`). Nothing is stored when a campaign is refused.
* **Languages:** a **Send in specific language** that is not a project language is refused (`CM-ERRORS-LANGUAGES-003`); a template without a translation for every project language too (`CM-ERRORS-LANGUAGES-004`). Both are checked again when the campaign starts.
* **An empty recipient list is refused** (`CM-ERRORS-CAMPAIGNS-008`). A token that still has no value when the email is rendered ends the campaign **Failed** with `CM-ERRORS-EMAILS-021`, naming the token.
* **Raw addresses get no unsubscribe links.** Campaigns to **Email Addresses** have no user behind each address, so the [preferences and unsubscribe links](/codemash/cloud/emails/preferences.md) are written as `#`. Send marketing to users.
* **CC and BCC go with every email.** With **Single email strategy** and three "To:" recipients, each CC address gets three copies.

## Change or remove it later

* A sent campaign cannot be edited. Use **Actions → Create new from this** on its [details](/codemash/cloud/emails/campaigns/details.md) to send it again with changes.
* **Stop** — while it is still sending: [Stop a campaign](/codemash/cloud/emails/campaigns/stop.md).
* **Delete** — on the details page, **Actions → Delete campaign...**; the browser asks "Delete this campaign? Its batches and message log are deleted with it. This cannot be undone." Only a Completed, Stopped or Failed campaign can be deleted.

## Do it from code

```ts
const { id } = await norbix.hub.notifications.createEmailCampaign({
  campaign: {
    source: 'Email',                              // AllUsers | SpecifiedUsers | Email | Collection | AccountUsers
    templateId: 'tmpl_3pLex0vXrqcLzOsJP8VLRx',     // Welcome email
    integrationId: 'int_6TG84uqtIL4HghyUx0EONk',   // required: Test Me (Fake)
    recipients: ['ada.lovelace@example.com'],
    mappedTokens: [
      { key: 'Recipient.FirstName', value: 'Ada', resolver: 'Custom' },
      { key: 'Email.SignatureId', value: 'emlsgn_2zT7jxLqeylWMYCPLzDSpm', resolver: 'Custom' },
      { key: 'Email.FooterId', value: 'emlftr_3xxahehZsa7l8kj90ytaxX', resolver: 'Custom' },
    ],
  },
});
console.log(id); // cmp_…
```

```sh
norbix hub notifications email campaign create --campaign '{"source":"Email","templateId":"tmpl_3pLex0vXrqcLzOsJP8VLRx","integrationId":"int_6TG84uqtIL4HghyUx0EONk","recipients":["ada.lovelace@example.com"],"mappedTokens":[{"key":"Recipient.FirstName","value":"Ada","resolver":"Custom"},{"key":"Email.SignatureId","value":"emlsgn_2zT7jxLqeylWMYCPLzDSpm","resolver":"Custom"},{"key":"Email.FooterId","value":"emlftr_3xxahehZsa7l8kj90ytaxX","resolver":"Custom"}]}'
```

`source` picks the recipient fields: `AllUsers` (`rolesNames`), `SpecifiedUsers` and `AccountUsers` (`userRecipients`, `userCc`, `userBcc`, `singleEmailStrategy`), `Email` (`recipients`, `recipientsCc`, `recipientsBcc`), `Collection` (`schemaName`, `fields`, `fieldType`). Optional: `language` (one project language for everybody) and `initiatorId` (the "on behalf of" user, `usr_…`).

API: [Create Email Campaign](/codemash/api-reference/notifications/email/create-email-campaign.md) · [Get Email Template Available Tokens](/codemash/api-reference/notifications/email/get-email-template-available-tokens.md)