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

# On label added

> Start an automation when Gmail adds a label to a message.

`onGmailLabelAdded` subscribes an automation to label additions in the connected Gmail mailbox. It emits both user-label and system-label changes.

## Example

```ts automations/prioritize-customer-email.automation.ts theme={null}
import { automation, filter } from "automate.ax"
import {
  markGmailMessagesAsImportant,
  onGmailLabelAdded,
} from "automate.ax/gmail"

export default automation("Prioritize customer email", () => {
  const customerEmail = filter(onGmailLabelAdded(), ({ labels }) =>
    labels.some(({ name }) => name === "Customer"),
  )

  markGmailMessagesAsImportant({
    messageIds: customerEmail.message.messageId,
  })
})
```

## Options

| Property  | Type                                              | Required | Description                                                                                       |
| --------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `account` | `string \| IntegrationAccountReference<"google">` | No       | Static Google account binding to watch. Defaults to the project's default Google account binding. |

The account selection must be static. Call `onGmailLabelAdded()` without an options object to use the default Google binding.

## Trigger data

Returns a `Signal<GmailLabelChange>` for each Gmail history change:

```ts theme={null}
interface GmailLabelChange {
  labels: {
    labelId: string
    name?: string
  }[]
  message: Message
}
```

`message` is the same fully parsed shape returned by [Get message](/reference/integrations/gmail/actions/get-message). One event can contain several labels when Gmail records them in the same change. Use `labelId` as the stable identity; `name` reflects the label's current name when Gmail can resolve it.