> ## 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.

# Modify labels

> Add and remove multiple Gmail labels in one batch request.

`modifyLabels` adds and removes multiple labels across one or many messages in a single Gmail request. Use it when a workflow stage should replace several labels atomically instead of running separate label actions.

## Example

Move new messages from a `Triage` label to a `Processed` label:

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

export default automation("Update Gmail workflow labels", () => {
  const email = onNewEmail()

  modifyLabels({
    add: ["Processed"],
    messageIds: email.messageId,
    remove: ["Triage"],
  })
})
```

Both labels must already exist in the selected Gmail account.

## Inputs

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

Provide at least one non-empty `add` or `remove` list. 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, and names and IDs may be mixed in either list. If any requested label cannot be resolved, the action fails before modifying messages.

## Output

The action returns a `Signal<string[]>` containing the modified message IDs in input order.

<Note>
  The action changes labels on individual messages. Supplying Gmail system
  labels such as `INBOX`, `UNREAD`, or `STARRED` changes the corresponding Gmail
  state.
</Note>