On new email

onNewEmail subscribes an automation to messages newly added to the connected Gmail inbox. Use it for inbound-email workflows such as triage, routing, attachment processing, and reply preparation. The trigger emits the same fully parsed message shape as Get message, including headers, MIME bodies, labels, and attachment File objects.

Example

automations/read-new-email.automation.ts

import { automation } from "automate.ax"
import { markAsRead, onNewEmail } from "automate.ax/gmail"

export default automation("Mark new Gmail messages as read", () => {
  const email = onNewEmail()

  markAsRead({
    messageIds: email.messageId,
  })
})

Options

Property	Type	Required	Description
`account`	`string \| IntegrationAccountReference<"google">`	No	Static Google account binding to watch. Defaults to the project’s default Google account binding.

You can call onNewEmail() without an options object. Unlike action inputs, the trigger’s account selection must be static: a Signal cannot choose which mailbox to watch at runtime.

Trigger data

Returns a Signal<Message> for each qualifying message:

interface Message {
  messageId: string
  threadId: string
  historyId?: string
  labelIds: string[]
  attachments: Attachment[]
  bcc: Mailbox[]
  cc: Mailbox[]
  deliveredTo?: string
  from?: Mailbox
  headers: { name: string; value: string }[]
  html?: string
  inReplyTo?: string
  receivedAt: Date | null
  references: string[]
  replyTo: Mailbox[]
  returnPath?: string
  rfc822MessageId?: string
  sender?: Mailbox
  sentAt?: Date
  sizeEstimate?: number
  snippet?: string
  subject: string
  text?: string
  to: Mailbox[]
}

interface Mailbox {
  address: string
  name?: string
}

interface Attachment {
  contentId?: string
  description?: string
  disposition?: "attachment" | "inline"
  file: File
  filename: string
  mimeType: string
  related: boolean
}

Use signal property access to connect trigger data directly to action inputs, as email.messageId does in the example. Use email.transform(...) when you need to derive a new typed value from the complete message.

Behavior

Only messages newly added to Gmail’s INBOX qualify. Existing inbox messages are not replayed when you deploy the trigger.
Automate.ax parses the complete raw message before starting the automation. Attachments and inline MIME parts are included as File objects.
text is derived from html when the message has no plain-text alternative.
Gmail message IDs are used for idempotency, so repeated provider notifications for the same message do not create duplicate events.

Email formats vary. html, text, from, and sender-supplied date fields can be absent, while receivedAt can be null. Handle optional fields when your automation accepts mail from varied senders.

Get started

Concepts

Reference

Example

Options

Trigger data

Behavior

​Example

​Options

​Trigger data

​Behavior

Example

Options

Trigger data

Behavior