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

# List labels

> List Gmail system and user labels with their available visibility, count, and color metadata.

`listLabels` returns every system and user label in the connected Gmail mailbox. Use it to discover immutable label IDs before searching, modifying, updating, or deleting labels.

## Example

```ts automations/list-gmail-labels.automation.ts theme={null}
import { automation } from "automate.ax"
import { listLabels } from "automate.ax/gmail"

export default automation("List Gmail labels", () => {
  listLabels({})
})
```

## Inputs

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

The account can also be supplied by a compatible `Signal`.

## Output

Returns a `Signal<GmailLabel[]>`. Each label contains:

```ts theme={null}
interface GmailLabel {
  labelId: string
  name: string
  type?: "system" | "user"
  labelListVisibility?: "labelHide" | "labelShow" | "labelShowIfUnread"
  messageListVisibility?: "hide" | "show"
  color?: {
    backgroundColor: string
    textColor: string
  }
  messagesTotal?: number
  messagesUnread?: number
  threadsTotal?: number
  threadsUnread?: number
}
```

Gmail does not supply every optional field for every label. For example, system labels and user labels can expose different visibility, color, and count metadata.

<Note>
  Use `labelId` for durable references and for `labelIds` search filters.
  Display names are intended for people and can be renamed.
</Note>