On new email

gmail.onNewEmail handles new inbox messages for triage, routing, attachment processing, or reply preparation. Trigger data matches Get message, including headers, message bodies, labels, and attachment File objects.

Example

automations/read-new-email.automation.ts

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

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

  gmail.markMessagesAsRead({
    messageIds: email.messageId,
  })
})

Options

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

Call gmail.onNewEmail() without options to use the project binding. The watched account can’t change at runtime.

Trigger data

Returns 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
}

Pass properties such as email.messageId to actions. Use email.transform(...) to derive other values.

Behavior

Only messages newly added to Gmail’s INBOX qualify. Existing inbox messages aren’t replayed when you deploy the trigger.
Automate.ax parses the complete raw message before starting the automation. It includes attachments and inline message parts as File objects.
Automate.ax derives text from html when the message has no plain-text alternative.
An authenticated Automate.ax message doesn’t wake the automation that sent it. Other automations watching the mailbox still receive the event.
Automate.ax uses Gmail message IDs for idempotency, so repeated provider notifications for the same message don’t 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.

Built-in triggers

Built-in actions

Runtime utilities

Integrations

Example

Options

Trigger data

Behavior

​Example

​Options

​Trigger data

​Behavior

Example

Options

Trigger data

Behavior