Add label

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:

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.

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.

⌘I

Get started

Concepts

Reference

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output