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

# Create label

> Create a user-owned Gmail label with optional visibility and color settings.

`createLabel` creates a user-owned Gmail label and returns its complete metadata. Use it when an automation needs a stable label to categorize messages or threads.

## Example

```ts automations/create-follow-up-label.automation.ts theme={null}
import { automation } from "automate.ax"
import { createLabel } from "automate.ax/gmail"

export default automation("Create a Gmail follow-up label", () => {
  createLabel({
    name: "Automate.ax/Follow up",
    labelListVisibility: "labelShow",
    messageListVisibility: "show",
  })
})
```

## Inputs

| Property                | Type                                                | Required | Description                                                                              |
| ----------------------- | --------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name`                  | `string`                                            | Yes      | Human-readable label name. Nested names can use Gmail's `/` convention.                  |
| `labelListVisibility`   | `"labelHide" \| "labelShow" \| "labelShowIfUnread"` | No       | Visibility in Gmail's label list.                                                        |
| `messageListVisibility` | `"hide" \| "show"`                                  | No       | Visibility beside messages in Gmail's message list.                                      |
| `color`                 | `{ backgroundColor: string; textColor: string }`    | No       | Hex colors from Gmail's supported label-color palette.                                   |
| `account`               | `string \| IntegrationAccountReference<"google">`   | No       | Google account binding to use. Defaults to the project's default Google account binding. |

Each input can also be a compatible `Signal` from an earlier trigger or action.

## Output

Returns a `Signal<GmailLabel>`:

```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
}
```

Keep the returned `labelId` when later actions need an immutable identifier. A label's display name can change.

<Note>
  Gmail only accepts predefined background and text color combinations.
  Unsupported color pairs are rejected by Gmail.
</Note>