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

# Send email

> Send a new plain-text or HTML message through Gmail.

`sendEmail` sends a new Gmail message. Use it when you know the recipients and
content up front rather than replying within an existing conversation.

## Example

```ts automations/send-report.automation.ts theme={null}
import { automation, onHttpRequest } from "automate.ax"
import { sendEmail } from "automate.ax/gmail"

export default automation("Send the weekly report", () => {
  onHttpRequest({ scope: "automation" })

  sendEmail({
    to: { address: "reader@example.com", name: "Report reader" },
    subject: "Your weekly report",
    html: "<h1>Weekly report</h1><p>The report is ready.</p>",
  })
})
```

When `html` is present and `text` is omitted, Automate.ax derives a plain-text
alternative from the HTML.

## Inputs

| Input         | Type                                              | Required          | Default               | Description                                        |
| ------------- | ------------------------------------------------- | ----------------- | --------------------- | -------------------------------------------------- |
| `to`          | `Recipient \| Recipient[]`                        | Yes               | —                     | One or more primary recipients.                    |
| `subject`     | `string`                                          | Yes               | —                     | Message subject.                                   |
| `html`        | `string`                                          | One body required | —                     | HTML body.                                         |
| `text`        | `string`                                          | One body required | Derived from `html`   | Plain-text body.                                   |
| `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.             |
| `attachments` | `Attachment[]`                                    | No                | `[]`                  | Files and inline MIME parts.                       |
| `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 used to send 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`.

<Note>
  Gmail may reject or replace a `from` address that is not configured as a
  send-as alias on the connected account.
</Note>

## Output

Returns a `Signal<MessageMetadata>` with:

| Property    | Type                  | Description                                                                  |
| ----------- | --------------------- | ---------------------------------------------------------------------------- |
| `messageId` | `string`              | Immutable Gmail ID of the sent message.                                      |
| `threadId`  | `string`              | Immutable Gmail ID of its conversation.                                      |
| `historyId` | `string \| undefined` | Latest mailbox history record affecting the message, when Gmail supplies it. |
| `labelIds`  | `string[]`            | Gmail system and user label IDs applied to the message.                      |

Keep `messageId` for actions that operate on one message and `threadId` for
actions that operate on the conversation.