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

# On new email

> Start an automation when a new message arrives in a Gmail inbox.

`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](/reference/integrations/gmail/actions/get-message), including headers, MIME bodies, labels, and attachment `File` objects.

## Example

```ts automations/read-new-email.automation.ts theme={null}
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:

```ts theme={null}
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.

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