Forward a message

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

automations/forward-invoices.automation.ts

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.

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

Get started

Concepts

Reference

Example

Inputs

Output

​Example

​Inputs

​Output

Example

Inputs

Output