---
title: Forward email transport
---

# Forward email transport

## What it is

The `forward_email` automation action sends one email per recipient when its rule fires. As of 2026-04-23 it supports two transports: **Gmail** (default) and **AgentMail**.

| Field                    | Default | Effect                                                                                                                                                                                   |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transport: 'gmail'`     | yes     | Sends via the Google account connected in Settings → Channels → Google. Requires an OAuth refresh token.                                                                                 |
| `transport: 'agentmail'` | no      | Sends via the AgentMail inbox configured in Settings → Email Inbound. Requires the AgentMail API key (Windows Credential Manager via `~/.claude/skills/agentmail/credential.ps1 store`). |

The field is **optional** in the schema with default `'gmail'`. Existing rules without the field continue to send via Gmail unchanged.

## Where to find it

There is no screen of its own. The transport is one choice on the forward-email action, made wherever you build the automation rule that uses it.

## How it behaves

### Pre-flight gates (CLI control server)

`POST /automation/rules`, `PATCH /automation/rules/:id`, and `POST /automation/test-forward-email` all walk the action chain and validate readiness for each `forward_email` action's transport. A 409 response with a descriptive `error` is returned if:

- `transport: 'gmail'` and no Google refresh token is configured.
- `transport: 'agentmail'` and `settings.emailInboundInboxId` is empty.
- `transport: 'agentmail'` and the AgentMail API key cannot be read from the credential store.

### Failure notification

After three consecutive per-rule failures the executor fires a desktop notification once. The body text is transport-aware:

- Gmail: `Rule failed 3 times — check your Google connection`
- AgentMail: `Rule failed 3 times — check your AgentMail API key (~/.claude/skills/agentmail/credential.ps1 store)`

### v1 limitations

- No rule-editor UI toggle. Rules with `transport: 'agentmail'` are creatable only via the CLI control server REST API. UI toggle is deferred to V2 (added when both transports are wired).
- Single from-inbox. The AgentMail send-from inbox is the same `emailInboundInboxId` used to receive email — no per-rule override.

## For agents

### Where the code lives

- Schema: [src/shared/ipc-schemas.ts](../../src/shared/ipc-schemas.ts) — `forwardEmailActionSchema`
- Executor branch: [src/main/services/automation/legacy/automation-action-executor.ts](../../src/main/services/automation/legacy/automation-action-executor.ts) — `executeForwardEmail`
- Send wrapper: [src/main/services/agentmail-client.ts](../../src/main/services/agentmail-client.ts) — `sendMessage`
- Pre-flight gate helper: [src/main/services/cli/cli-automation-idempotency.ts](../../src/main/services/cli/cli-automation-idempotency.ts) — `checkForwardEmailReadiness`

## Related

The [helpdesk](helpdesk.md) sends its replies through the same outbound-email machinery, and [Feedback channel opt-out](feedback-channel-opt-out.md) is where you silence Omniscio's own outbound reports for your install.