> 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/files/triggers/new.md).

# Create a trigger

Create a files trigger — pick the event and the folder, then the action (send an email, push or SMS, call a webhook, run code, send an in-app event).

**Where:** Files → Triggers → **Add New** · `/projects/<project>/files/triggers/new`

## Before you start

* For **Send Email**: the Email module is on, with an [email template](/codemash/cloud/emails/templates.md) and an email integration (every project gets the Fake one, **Test Me**). For **Send Push Notification** / **Send SMS**: the same in that module. For **Call Webhook**: a destination in [Project → Settings → Webhooks](/codemash/cloud/project/settings/webhooks.md).
* To pick a folder from a list, the project needs a files integration with that folder — see [Browser](/codemash/cloud/files/browser.md). You can also type the folder.

## Steps

1. Press **Add New**. Under **If this** → **Select trigger actions**, pick the event: **When uploaded** or **When deleted**. The box below tells you what the action gets (*Usage: 'New\.File.\*'*). Under **In this folder**, type a folder or pick it in the list below the field (**Every file**, `catalog`, `mugs`, …), for example `catalog`. Only files in this folder and its subfolders fire the trigger; leave it empty to react to every file. **Add activation code** adds code that runs first and can stop the trigger.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-a65215b601f28a320d94071624428f62c7db0082%2Ftriggers-new-1.png?alt=media" alt="Add New Trigger: When uploaded is picked, Usage: &#x27;New.File.*&#x27;, In this folder catalog, with the folder list Every file / catalog"><figcaption><p>The event and the folder.</p></figcaption></figure>
2. Under **... then**, open the action list and pick the action.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-00fa5a00226aa1bd53930f21fc3c4ee18309c50b%2Ftriggers-new-2.png?alt=media" alt="The action list open: Run Code, Send Email, Send Push Notification, Send SMS, Call Webhook, Send In-App (Realtime / SSE)"><figcaption><p>The action list.</p></figcaption></figure>

   | Action                                                     | What it does                                                                                                                                                                          |
   | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Run Code**                                               | Invokes a serverless function with the event data.                                                                                                                                    |
   | **Send Email** / **Send Push Notification** / **Send SMS** | Sends a template to the recipients you choose.                                                                                                                                        |
   | **Call Webhook**                                           | POSTs a signed event (`files.file.uploaded` or `files.file.deleted`) to the destinations you tick. **Save** stays off until you tick an enabled destination subscribed to that event. |
   | **Send In-App (Realtime / SSE)**                           | Sends the event live to connected apps or AI agents.                                                                                                                                  |
3. For **Send Email**, choose **Email Addresses** and type the address in **To: \***, for example `catalog-team@example.com`. **Single email strategy** sends each address its own email; **CC:** and **BCC:** are optional. Under **Template Details**, choose **Select template** (for example `New catalog file`) and **Send in specific language** (leave **Each recipient's language**).

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-f3eca2211212d4617491dc5cf6249339ffac1cf8%2Ftriggers-new-3.png?alt=media" alt="Send Email with Email Addresses, To catalog-team@example.com, then Template Details with Select template New catalog file (Transactional)"><figcaption><p>Recipients and template.</p></figcaption></figure>
4. **Template Tokens** lists the tokens of the template. Give each one a value: type it, or press the tag button next to a token and pick a value (Project, Initiator, Recipient, Email Signatures, Email Footers). Until each has a value, a yellow box lists what is *Still missing*.

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-ad7398e5062d23de175ed45a74fa336663b421a8%2Ftriggers-new-4.png?alt=media" alt="Template Tokens all set: Recipient.FirstName Catalog team, Email.SignatureId emlsgn_…, Email.FooterId emlftr_…, Project.Name, Project.Url"><figcaption><p>Every token has a value.</p></figcaption></figure>
5. Under **Advanced settings**, **Send email on behalf of** sets who speaks in the message; **Select email provider** is set to the project default (**Test Me (Fake)** here). Then fill the trigger's own fields and press **Save**:

   | Field                    | Required | What it does                                                           | Example                                                  |
   | ------------------------ | -------- | ---------------------------------------------------------------------- | -------------------------------------------------------- |
   | Order                    | no       | Run order when several triggers listen to one event; lower runs first. | `1`                                                      |
   | Name the trigger         | yes      | The name in the list.                                                  | `Tell the catalog team`                                  |
   | Description              | no       | Free text.                                                             | `Emails the catalog team when a file lands in catalog/.` |
   | Is this trigger enabled? | no       | On: the trigger runs. Off: saved but quiet.                            | on                                                       |

   <figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-fae7988ae001db6c66d5b098002b193300e5682b%2Ftriggers-new-5.png?alt=media" alt="Lower part of the form: Select email provider Test Me (Fake), Order, Name the trigger Tell the catalog team, Description, the switch Is this trigger enabled? drawn off, Cancel and Save"><figcaption><p>The trigger's own fields.</p></figcaption></figure>

{% hint style="warning" %}
A new trigger starts **enabled**. Today the **Is this trigger enabled?** switch is still drawn in the off position on a new trigger; that is a display fault — the trigger is saved enabled (the list shows **Enabled: Yes**). Disable it from the **Actions** menu if it should not run yet.
{% endhint %}

## Result

Cloud goes back to **File Triggers** with the new row (**When uploaded**, **Send Email**, **Enabled: Yes**). The next matching file runs it: in the example, uploading `catalog/summer-2026-catalog.pdf` produced an email campaign with status **Completed** through **Test Me**, visible in **Email → Campaigns**. A file uploaded into `mugs` does not fire it.

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-6e98ff0212905c0020a1b0d9cf2e230ed56cca69%2Ftriggers-new-6.png?alt=media" alt="File Triggers list with Tell the catalog team, When uploaded, Send Email, Enabled Yes"><figcaption><p>The new trigger in the list.</p></figcaption></figure>

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-f9d4c590087d69b690ef6471004e98f73a0079a6%2Ftriggers-new-7.png?alt=media" alt="Email Campaigns list with one row: Completed, Specific Email Addresses, template New catalog file, integration Test Me (Default)"><figcaption><p>The email the trigger sent, in Email → Campaigns.</p></figcaption></figure>

A run that cannot send (template misses a project language, provider off) marks the trigger **Needs attention**.

## Change or remove it later

* **Edit** — [Edit a trigger](/codemash/cloud/files/triggers/edit.md).
* **Disable / Enable** — [Enable or disable a trigger](/codemash/cloud/files/triggers/enable.md).
* **Delete** — [Delete a trigger](/codemash/cloud/files/triggers/delete.md).

## Do it from code

```ts
const { id } = await norbix.hub.files.saveFilesTrigger({
  trigger: {
    type: 'Files',
    when: 'OnFileUploaded',
    folder: 'catalog/2026',
    name: 'Tell sales about 2026 catalogs',
    isEnabled: true,
    action: {
      type: 'email',
      templateId: 'tmpl_73E0M90SdGHBZtZM1Y3E1k', // New catalog file
      integrationId: 'int_6OFbF0V9iR8sGMKr2loYAU', // the email provider (Test Me)
      deliverySettings: {
        recipientsSourceType: 'Email',
        recipients: ['sales@example.com'],
        mappedTokens: [
          { key: 'Recipient.FirstName', value: 'Sales team', resolver: 'Custom' },
          { key: 'Email.SignatureId', value: 'emlsgn_62lhoSNxPmBjR7KoUNfE8n', resolver: 'Custom' },
          { key: 'Email.FooterId', value: 'emlftr_6hU4LyFZt7kY9WANxED3UQ', resolver: 'Custom' },
          { key: 'Project.Name', value: 'Project.Name', resolver: 'Project' },
          { key: 'Project.Url', value: 'https://acme.example', resolver: 'Custom' },
        ],
      },
    },
  },
});
console.log(id); // trg_1p50DsItoELswoqBLXU157
```

```sh
norbix hub files trigger save --trigger:json '{"type":"Files","when":"OnFileDeleted","name":"Temp (cli)","isEnabled":true,"action":{"type":"email","templateId":"tmpl_73E0M90SdGHBZtZM1Y3E1k","integrationId":"int_6OFbF0V9iR8sGMKr2loYAU","deliverySettings":{"recipientsSourceType":"Email","recipients":["ops@example.com"]}}}'
```

The [SDK reference](/codemash/sdks/files/triggers/save-files-trigger.md) has one example per action. The client setup is on the [Files page](/codemash/cloud/files.md#use-it-from-code). API: [Save Files Trigger](/codemash/api-reference/files/triggers/save-files-trigger.md)