> ## 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 mailbox changed

> Run an automation for any normalized Gmail mailbox history change.

`gmail.onMailboxChanged` is the broad Gmail history trigger. Use it when one automation must handle message additions, permanent deletions, label additions, and label removals.

## Example

```ts automations/audit-mailbox.automation.ts theme={null}
import { automation } from "automate.ax"
import { gmail } from "automate.ax/gmail"

export default automation("Audit Gmail changes", () => {
  const change = gmail.onMailboxChanged()

  // Route the Gmail mailbox change by type.
})
```

## Options

`account` is a static Google Account binding and defaults to the project binding. It can't change at runtime.

## Trigger data

Returns a discriminated union with `changeType`:

```ts theme={null}
type GmailMailboxChange =
  | {
      changeType: "messageAdded"
      historyId: string
      message: Message
    }
  | {
      changeType: "messageDeleted"
      historyId: string
      messageId: string
      threadId: string
    }
  | {
      changeType: "labelAdded" | "labelRemoved"
      historyId: string
      labels: { labelId: string; name?: string }[]
      message: Message
    }
```

Added messages and label changes contain the parsed message shape from [Get message](/reference/integrations/gmail/actions/get-message). Permanently deleted messages contain stable IDs because Gmail can no longer return the message.

Moving a message to Trash is a label change, not a permanent deletion. Use the dedicated semantic triggers when one lifecycle is sufficient.