Modify labels

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:

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.

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

Get started

Concepts

Reference

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output