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

# Forward a message

> Forward a Gmail message with optional introductory content and attachments.

`forward` sends an existing Gmail message to new recipients. It builds a
standard forwarded-message block from the original headers and preserves the
original attachments by default.

## Example

```ts automations/forward-invoices.automation.ts theme={null}
import { automation } from "automate.ax"
import { forward, onNewEmail } from "automate.ax/gmail"

export default automation("Forward new invoices", () => {
  const email = onNewEmail()

  forward({
    messageId: email.messageId,
    to: "accounting@example.com",
    text: "A new invoice arrived in the shared mailbox.",
  })
})
```

## Inputs

| Input                | Type                                              | Required | Default                                | Description                                                        |
| -------------------- | ------------------------------------------------- | -------- | -------------------------------------- | ------------------------------------------------------------------ |
| `messageId`          | `string`                                          | Yes      | —                                      | Immutable Gmail ID of the message to forward.                      |
| `to`                 | `Recipient \| Recipient[]`                        | Yes      | —                                      | One or more primary recipients.                                    |
| `subject`            | `string`                                          | No       | Original subject prefixed with `Fwd: ` | Subject override. An existing exact `Fwd:` prefix is not repeated. |
| `html`               | `string`                                          | No       | None                                   | HTML introduction placed before the forwarded message.             |
| `text`               | `string`                                          | No       | Derived from `html`                    | Plain-text introduction placed before the forwarded message.       |
| `includeAttachments` | `boolean`                                         | No       | `true`                                 | Preserve the original message's attachments.                       |
| `attachments`        | `Attachment[]`                                    | No       | `[]`                                   | Additional files and inline MIME parts.                            |
| `cc`                 | `Recipient \| Recipient[]`                        | No       | None                                   | Carbon-copy recipients.                                            |
| `bcc`                | `Recipient \| Recipient[]`                        | No       | None                                   | Blind-copy recipients.                                             |
| `from`               | `Recipient`                                       | No       | Gmail account address                  | Sender address or configured Gmail send-as alias.                  |
| `replyTo`            | `Recipient \| Recipient[]`                        | No       | None                                   | Addresses that should receive replies.                             |
| `headers`            | `Record<string, string>`                          | No       | None                                   | Additional RFC 5322 headers.                                       |
| `priority`           | `"high" \| "normal" \| "low"`                     | No       | Not set                                | Importance encoded in standard message headers.                    |
| `account`            | `string \| IntegrationAccountReference<"google">` | No       | Project default                        | Connected Google account that reads and sends the message.         |

`Recipient` is an email string or `{ address: string; name?: string }`.
`Attachment` is a `File` or an object containing `file` with optional
`filename`, `contentId`, and `disposition: "attachment" | "inline"`.

Every input, including `account`, also accepts a compatible `Signal`.

<Note>
  Preserving original attachments requires the automation to download and upload
  those files. Set `includeAttachments: false` when you only need the message
  content, especially for large messages.
</Note>

The action fails if Gmail does not return the source message's raw content.

## Output

Returns a `Signal<MessageMetadata>` with:

| Property    | Type                  | Description                                                         |
| ----------- | --------------------- | ------------------------------------------------------------------- |
| `messageId` | `string`              | Immutable Gmail ID of the forwarded message.                        |
| `threadId`  | `string`              | Immutable Gmail thread ID assigned to the forwarded message.        |
| `historyId` | `string \| undefined` | Latest mailbox history record affecting the message, when supplied. |
| `labelIds`  | `string[]`            | Labels applied to the forwarded message.                            |