> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Add label

> Apply an existing Gmail label to one or many messages.

`addLabel` applies one existing label to Gmail messages. Use it with user labels to categorize processed mail, route work, or record an automation stage. Gmail system labels can also change message state or placement.

## Example

Apply the `Processed` label to each newly received message:

```ts theme={null}
import { automation } from "automate.ax"
import { addLabel, onNewEmail } from "automate.ax/gmail"

export default automation("Label processed Gmail messages", () => {
  const email = onNewEmail()

  addLabel({
    label: "Processed",
    messageIds: email.messageId,
  })
})
```

The label must already exist in the selected Gmail account.

## Inputs

| Name         | Type                                 | Required | Description                                                                      |
| ------------ | ------------------------------------ | -------- | -------------------------------------------------------------------------------- |
| `label`      | `string`                             | Yes      | Label display name or immutable Gmail label ID.                                  |
| `messageIds` | `string \| string[]`                 | Yes      | One or up to 1,000 immutable Gmail message IDs.                                  |
| `account`    | `string \| Google account reference` | No       | Google account binding to use. Defaults to the project's default Google account. |

Every input field also accepts a compatible `Signal`; the example passes `email.messageId` directly.

Label IDs must match exactly. Display names are matched after trimming surrounding whitespace and ignoring capitalization. If the label does not exist in the selected account, the action fails without modifying the messages.

## Output

The action returns a `Signal<string[]>` containing the modified message IDs in input order. Pass that signal directly to another batch-friendly Gmail action.

<Note>
  This action updates messages, not entire threads, and does not create the
  label. Prefer dedicated actions such as `archive`, `markAsSpam`, and
  `markAsRead` when they express the system-label change you need.
</Note>