Forward a message

gmail.forwardMessage sends a message to new recipients, builds a forwarded-message block from its headers, and preserves attachments by default.

Example

automations/forward-invoices.automation.ts

import { automation } from "automate.ax"
import { gmail } from "automate.ax/gmail"

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

  gmail.forwardMessage({
    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	None	Immutable Gmail ID of the message to forward.
`to`	`Recipient \| Recipient[]`	Yes	None	One or more primary recipients.
`subject`	`string`	No	Original subject prefixed with `Fwd:`	Subject override. An existing exact `Fwd:` prefix isn’t 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 message 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.
Second argument: `{ 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". Inputs accept compatible signals.

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.

The action fails if Gmail doesn’t return the source message’s raw content. The forwarded message carries an authenticated automation origin. Gmail triggers don’t wake the automation that sent it, while other automations watching the mailbox still receive the event.

Output

Returns Signal<MessageMetadata>:

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`	Most recent mailbox history record affecting the message, when supplied.
`labelIds`	`string[]`	Labels applied to the forwarded message.

Built-in triggers

Built-in actions

Runtime utilities

Integrations

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output