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

# Trash

> Move one or many Gmail messages to Trash.

`trash` moves one or many Gmail messages to Trash using Gmail's dedicated trash operation. Use it when messages should leave the mailbox's active views but still be recoverable for as long as Gmail retains them.

## Example

Trash newly received messages with a known test marker:

```ts theme={null}
import { automation, filter } from "automate.ax"
import { onNewEmail, trash } from "automate.ax/gmail"

export default automation("Trash Gmail test messages", () => {
  const testMessage = filter(onNewEmail(), (message) =>
    message.subject.includes("[TEST]"),
  )

  trash({ messageIds: testMessage.messageId })
})
```

## Inputs

| Name         | Type                                 | Required | Description                                                                      |
| ------------ | ------------------------------------ | -------- | -------------------------------------------------------------------------------- |
| `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 the filtered message ID signal directly.

## Output

The action returns a `Signal<Array<{ messageId: string; threadId: string; historyId?: string; labelIds: string[] }>>` with Gmail's updated metadata for every message, in input order.

| Field       | Type                  | Description                                                                  |
| ----------- | --------------------- | ---------------------------------------------------------------------------- |
| `messageId` | `string`              | Immutable Gmail message ID.                                                  |
| `threadId`  | `string`              | Immutable ID of the thread containing the message.                           |
| `historyId` | `string \| undefined` | Latest mailbox history record affecting the message, when Gmail supplies it. |
| `labelIds`  | `string[]`            | Gmail system and user label IDs currently applied after the operation.       |

<Warning>
  Trashing is not permanent deletion, but Gmail can permanently delete retained
  Trash contents. `untrash` can restore a message only while Gmail still has it.
</Warning>

The action operates on individual message IDs. Trashing one message does not explicitly trash every message in its thread.