> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Email

> Send and receive mail at forge.gloo.com: the sender registry and From rule, inbound setup, routes that start workflows, answering a hold by email, rejections and limits.

Forge sends and receives email at `forge.gloo.com` through SendGrid. Email is a **transport**, not a capability of its own:

* **Outbound** mail is the `email` channel of the notifications domain, served by the `notifications/sendgrid` provider. Every send is a row in a durable outbox, so it survives a crashed action. Safe non-applied failures can retry; a workflow-owned request with a lost acknowledgement is held for reconciliation.
* **Inbound** mail is a second ingress transport beside [signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md). SendGrid Inbound Parse posts each message to a capability URL; Forge logs it, then routes it to a workflow, drops it, or delivers it as a reply to the hold, run, or thread it answers.

The SendGrid API key is the `sendgrid/api` Credential, resolved through the credential basket. A provider never holds the key itself. `gloo.com` mail stays on Google Workspace and is not touched.

## Senders

Forge writes from a fixed, code-owned registry. Adding a sender is a code change, not a console edit.

| Address | Display name | Reply policy | Purpose |
| - | - | - | - |
| `noreply@forge.gloo.com` | Forge | `drop` | Receipts and anything that must not be answered |
| `notifications@forge.gloo.com` | Forge Notifications | `tokenized` | Event mail from the bus; a reply lands on the run or thread |
| `approvals@forge.gloo.com` | Forge Approvals | `tokenized` | Holds; a reply resolves the hold |
| `help@forge.gloo.com` | Forge Support | `route: help` | Support, also an inbound route |
| `security@forge.gloo.com` | Forge Security | `route: security` | Alerts out, reports in |
| `forge@forge.gloo.com` | Forge | `drop` | Work products a workflow publishes (publish node, Email destination) |

**The From rule.** Forge resolves the `sendgrid/api` Credential at the most specific scope it can find: the org unit's, else the system one. When that Credential's `fromAddress` field is set, it is the From address, exactly as stored. When it is empty, the From address is `<localPart>@forge.gloo.com`. The display name always comes from the registry, never from the Credential.

> [!NOTE]
>
> An org-unit Credential with an empty `fromAddress` produces the `forge.gloo.com` defaults, even when the system Credential has a value. The more specific Credential wins as a whole; its fields are not merged with the system one.

**Reply policy.** A `drop` sender sets `reply_to` to `noreply@`. A `route:` sender sets it to that route's address. A `tokenized` sender splits a send to several people into one delivery per recipient. Each attempt mints a reply token and sets `reply_to` to `reply+<token>@forge.gloo.com` only when the delivery names a reply target (a hold, run, or thread) that is still live and has exactly one recipient, and only while that target holds fewer than 256 live tokens. Otherwise no token is minted and `reply_to` is `noreply@forge.gloo.com`.

**Platform → Email → Senders** in Forge Console shows each sender's effective From address for your org unit and whether a Credential overrides the default.

## Set up inbound mail

**1. DNS (IT owns this)**

`forge.gloo.com` needs an `MX 10 mx.sendgrid.net` record plus the SendGrid domain-authentication CNAMEs (SPF and DKIM). A name that is a CNAME cannot also carry an MX, so `forge.gloo.com` itself is an `A` record.

**2. Create the inbound token**

In **Platform → Email**, create the inbound token. This requires `webhooks:manage`. The full URL is shown **once**; Forge stores only a hash of the token and cannot show it again.

```
https://hooks.forge.gloo.com/api/email/inbound/sendgrid/emt_<token>
```

**3. Point SendGrid Inbound Parse at it**

In SendGrid, add an Inbound Parse host for `forge.gloo.com` and paste the URL. Leave "POST the raw, full MIME message" off; Forge parses SendGrid's default multipart form.

**4. Turn on the Event Webhook**

Point SendGrid's signed Event Webhook at `https://hooks.forge.gloo.com/api/email/events/sendgrid`. A partner with its own SendGrid account and an org-unit `sendgrid/api` Credential uses `/api/email/events/sendgrid/<orgUnitId>` instead. Paste SendGrid's verification key into the Credential's `eventWebhookPublicKey` field. A request with a bad signature answers `401` and writes nothing.

**5. Add routes**

See [Routes](#routes). Mail to a local part with no enabled route is logged `unrouted` and answered `200`, so SendGrid does not retry it.

> [!WARNING]
>
> The inbound URL is the credential. SendGrid Inbound Parse signs nothing, so anyone holding the URL can post mail into Forge. Treat an exposed URL as a leaked key and rotate it.

**Rotate** retires the old token: its URL answers `404` on the next request, and the new token keeps the old one's paused or active status. Paste the new URL into SendGrid straight away: mail posted to the old URL is refused with `404`.

**Pause** makes the URL answer `410` and writes nothing. SendGrid retries a non-2xx post for up to three days, so mail that arrives during a short pause is delivered once you resume.

### Inbound status codes

| Status | Meaning | SendGrid |
| - | - | - |
| `200` | Logged with a final disposition, or a duplicate of one | Done |
| `400` | The post is not a well-formed multipart message | Retries, then drops |
| `404` | Unknown or rotated token | Retries, then drops |
| `410` | Inbound mail is paused | Retries until you resume |
| `413` | Body over 20 MiB | Retries, then drops |
| `500` | Routing failed, the platform kill switch is on, or the route's trigger is at its active-run cap; the message is logged `failed`. Also returned when writing the log row itself fails; see below | Retries; the redelivery routes again |

Each status has one fixed JSON body, `{ "error", "message" }`, or `{ "ok": true, "message": "Accepted." }` for a `200`. A duplicate answers `200` with `{ "ok": true, "duplicate": true, "message": "Already processed." }`. The sender learns nothing beyond the status code and whether the message was a duplicate.

A `500` from routing leaves the row `failed`. A `500` from a step before routing (the duplicate check, storing attachments, or writing the log row) writes no `failed` row: a new message is not in the Inbound log until SendGrid redelivers it, and a redelivered message's earlier row stays as it was.

## Routes

A route says what happens to mail sent to one local part, such as `help@forge.gloo.com`. Routes are managed in **Platform → Email → Routes** and require `webhooks:manage`.

| Field | Values |
| - | - |
| Kind | `workflow` starts a run of the chosen workflow; `drop` logs the message `dropped` and does nothing else |
| Sender policy | `any`; `dkim_pass` requires an aligned DKIM pass; `known_person` also requires the From address to belong to an active person |
| Rate per minute | Workflow starts per minute for this route. Default **60**, maximum **600**, with bursts of up to 10 |
| Enabled | A disabled route is not matched; its mail is logged `unrouted` |

The local part `reply`, and any local part containing `+`, is reserved for reply tokens and cannot be a route.

Forge checks each envelope recipient at `forge.gloo.com` in order. The first `reply+<token>` address, or the first local part with an enabled route, decides where the message goes.

**Aligned DKIM pass.** A DKIM signature counts only when it passed and its signing domain equals the From domain or is a parent of it. A pass from an unrelated domain proves nothing about the sender, and `gloo.com` publishes `p=none`, so no receiving system enforces this alignment for us.

**What the workflow receives.** A routed run starts with the input `{ email }`, where `email` is the normalized message: `messageId`, `from`, `to`, `cc`, `subject`, `text`, `html`, `inReplyTo`, `references`, `headers`, `spf`, `dkim`, `senderIp`, `attachments`, and `receivedAt`. Under `known_person` the input is `{ email, claimedSenderPersonId }`: the id sits beside `email`, not inside it. That id is attribution only. The run starts as the `email-route:<routeId>` surface principal, which carries no person's authority. Each attachment is a file-hosting reference (`fileRef`), with its `filename`, `contentType`, and `size`. Every `reply+<token>` address in the message is cut to its first characters before the workflow sees it.

### Inbound dispositions

Every message is logged in **Platform → Email → Inbound log** before it is routed, so rejected and unrouted mail is still visible.

| Disposition | Reason | Meaning |
| - | - | - |
| `routed` | — | A run started, or a reply was delivered to its hold, run, or thread. The row links the target |
| `unrouted` | `no_route` | No reply token and no enabled route for any recipient |
| `dropped` | `route_drop` | The route's kind is `drop` |
| `dropped` | `rate_limited` | The route was over its per-minute budget |
| `failed` | `rate_limited` | A redelivery of a `failed` message found the route over its budget. It stays `failed` so SendGrid keeps redelivering |
| `dropped` | `unprocessable`, `gone` | The workflow could not accept the run |
| `rejected` | `dkim_fail` | The route requires an aligned DKIM pass and the message has none |
| `rejected` | `unknown_sender` | `known_person` route; the From address is not an active person |
| `rejected` | Reply reasons | See [Reply rejection reasons](#reply-rejection-reasons) |
| `failed` | `active_run_cap` | The route's workflow trigger already has 50 runs in progress. SendGrid gets `500` and redelivers; the redelivery routes once runs finish |
| `failed` | Varies | Infrastructure failure or the kill switch. SendGrid gets `500` and redelivers |

A redelivered message whose earlier row is `received` or `failed` reuses that row and its attachments and routes again. A repeat Message-ID within 7 days whose earlier row has a final disposition answers `200` and changes nothing.

## Reply by email

When a `tokenized` send mints a reply token (see [Reply policy](#senders)), its `reply_to` address carries it: `reply+<token>@forge.gloo.com`. The token binds a reply to one hold, run, or thread. Forge stores only a hash of it and redacts the token from every operator view, run input, run event, and thread message.

| Target | Uses | Expires |
| - | - | - |
| Hold | Once. Resolving the hold revokes every token for it | With the hold |
| Run | Unlimited | 30 days after it is minted |
| Thread | Unlimited | 30 days after it is minted |

A use is spent only when the reply is acted on. A rejected or unparsed reply does not use up an approver's single use.

### Answering a hold

Email presents the same three kinds of hold as Slack: approvals, questions, and confirmations. Each email from `approvals@forge.gloo.com` says how to reply. Forge reads the reply from the first line that is not empty and not quoted, and stops at the quoted original. Words are matched case-insensitively, and a trailing `.` or `!` is ignored.

| Hold | Reply | Resolves as |
| - | - | - |
| Approval | **approve** or **reject** on the first line. Any lines after it are sent as your comment. Accepted: `approve`, `approved`, `yes`, `lgtm` and `reject`, `rejected`, `no`, `deny` | Approved or rejected, with the comment |
| Confirmation | **confirm** or **cancel** on the first line. Accepted: `confirm`, `confirmed`, `yes` and `cancel`, `cancelled`, `no` | Confirmed or cancelled |
| Question | Your answer, above the quoted text, up to 4,000 characters | The answer text |
| Question with choices | The email lists the choices numbered. Put one choice, or its number, on the first line | The choice as listed |

A hold is resolved by email only when all four checks pass:

1. **The token** is found, not expired, not revoked, and not used.
2. **The sender** is the exact address the token was sent to.
3. **DKIM** passes and is aligned with the From domain.
4. **Permission.** That person holds every one of: the hold's own resolve permission, **and** `approvals:approve`, **and** any other key the console requires for that kind of hold. Holding only one of them is not enough. The email door's own audit row records the approval release rules as `not_evaluated`: approving a held agent or tool call is then decided by the shared approval resolver, which applies them against the sender's sign-in — the sender must be able to do the held action at its scope, and a person upstream of it (who started it, owns the agent, or last changed its grants or the tool's declaration) is refused while someone else could approve.

A From address without a token authenticates no one. The token is the authentication factor, like a magic link sent to one mailbox.

A reply the parser does not understand gets one short "not understood" email from `approvals@` that repeats how to answer that kind of hold, and leaves the hold open. Auto-replies get nothing. Every other rejection sends nothing back, so a guessed token learns nothing.

> [!NOTE]
>
> Answering by email is off until an operator adds the `sendgrid` provider to the `human_interaction` chain. Readiness-risk holds, which need an emergency permission and an org-unit scope check, cannot be resolved by email at all. A Trust Fabric approval is resolved by email only as an approval.

### Run and thread replies

A reply to a run token is recorded as `run.emailReceived` in the run's audit log (the run view's Logs and Audit tabs). When a person started the run, that person gets a bell notification. A run no person started rings no bell. A run reply is attributed to a person only when it comes from the address the token was sent to with an aligned DKIM pass; otherwise it is recorded as an unverified sender, and the From address is never resolved to a person.

A reply to a thread token is appended to the chat thread as the token's person only when it comes from the address the token was sent to with an aligned DKIM pass. A thread reply that fails either check is rejected with `sender_unverified` and nothing is written to the thread.

### Reply rejection reasons

| Reason | Applies to | Cause |
| - | - | - |
| `token_not_found` | All | No token matches |
| `token_expired` | All | Past its expiry |
| `token_revoked` | All | Revoked, for example because the hold was already resolved |
| `token_exhausted` | Hold | The single use is spent |
| `target_missing` | Run, thread | The run or thread no longer exists |
| `sender_mismatch` | Hold | From is not the address the token was sent to |
| `dkim_fail` | Hold | No aligned DKIM pass |
| `hold_not_pending` | Hold | The hold is already resolved or expired |
| `not_email_resolvable` | Hold | This kind of hold cannot be resolved by email |
| `not_understood` | Hold | The reply does not answer the hold: no recognized decision or confirmation word, no choice, or an empty or over-long answer |
| `not_authorized` | Hold | The person lacks a permission the hold requires |
| `resolution_refused` | Hold | The resolve call refused; the reason carries its message after a colon |
| `sender_unverified` | Thread | From is not the address the token was sent to, or no aligned DKIM pass |

A rejected reply changes nothing: a hold stays as it was, and nothing is written to a thread.

## Outbound delivery

Each send is one row in the outbox, visible in **Platform → Email → Deliveries** with its status, retry count, last error, and SendGrid message id. Bodies are not shown there.

| Outcome | Status |
| - | - |
| SendGrid accepted the message | `sent`, then `delivered`, `bounced`, `dropped`, or `spam` from the Event Webhook |
| `429`, any `5xx`, or a timeout | `retrying` after 5 s, 15 s, 30 s, then 60 s; `failed` after the fifth attempt |
| Any other `4xx` | `failed`, not retried, with the error kept |
| Every recipient suppressed | `dropped`, with error `suppressed` |
| No SendGrid API key resolves for the org unit or the system | `failed`, with error `sendgrid_not_configured`; not retried |
| No recipient to send to, such as operator mail with no `operatorRecipient` on the Credential | `failed`, with error `no_recipients`; not retried |
| `text` or `html` over 256 KiB | `failed`, with error `body_too_large`; never truncated |
| An approval request whose hold was already resolved, expired, or removed before it was sent | `dropped`, with error `hold_resolved`; not sent |

A hard bounce or a spam report adds the address to the suppression list, and Forge skips it on later sends. A retry is sent from the row alone; it does not need the caller that enqueued it.

### Publish to email

A workflow [publish node](https://docs.gloo.com/forge/build/compose-a-workflow.md) with the **Email** destination sends its output from `forge@forge.gloo.com` through this outbox. Nothing calls SendGrid directly.

* **One delivery per recipient.** Each address on the node gets its own row and its own email, so recipients do not see each other. Replies go to `noreply@` and are not read.
* **Recipients are addresses, not Forge people.** The node lists 1 to 50 entries, none on `forge.gloo.com`. An entry is a static address, or a whole-entry token that takes the address from the run: `{{workflow.x}}` reads a workflow input, and `{{inputs.x}}` (or `{{x}}`) reads a node input wired from an upstream step. The subject may carry the same tokens. The publish gate checks the entries (`PUBLISH_EMAIL_RECIPIENTS_INVALID`, `PUBLISH_EMAIL_SUBJECT_MISSING`), and the provider checks the concrete addresses again at send time, because draft test runs skip the gate.
* **Tokens resolve when the step starts.** A value that holds several addresses separated by commas or semicolons, or a list of addresses, becomes several recipients, and a repeated address is sent once. A missing or empty value, an invalid address, or more than 50 recipients fails the step with an error that names the value; Forge never drops a recipient silently. The run journal records the resolved addresses, so a retried step sends to the same people.
* **Forge renders the body.** The published markdown becomes the text part, and an HTML part in Forge's email layout. Raw HTML in the body is escaped, links keep only `http`, `https`, and `mailto` targets, and images become links; nothing is embedded or fetched.
* **Files attach, or become links.** Files stored in Forge attach under their own names while the total stays within 8 MB. Larger files, and files stored outside Forge, are listed as links under **Files**. A file that has neither fails the step.
* **No duplicate sends.** Each row carries the key `publish:<run>:<node>:<attempt>:<recipient>`, so a retried step reuses the rows that attempt already wrote. Restarting the run from the step is a new attempt and sends again. A row that failed at enqueue, such as `body_too_large`, fails the step.
* **The step completes when the email is queued**, not when it is delivered, as with Slack publish. The delivery outcome is on **Platform → Email → Deliveries**.

Delivery is **at least once**. A send that dies after SendGrid accepted the message is normally caught by SendGrid's `processed` event, which marks the row `sent` before any retry. If no event arrives within the two-minute send lease, the message can go out twice.

#### Example: acknowledge a ticket requester

A capability-URL run receives a ticket, including the requester's address, as workflow inputs. The workflow declares `requesterEmail` and `ticketTitle` as required inputs, and its last node is an Email publish node:

| Field | Value |
| - | - |
| Recipients | `{{workflow.requesterEmail}}`, `support-leads@example.com` |
| Subject | `We received your ticket: {{workflow.ticketTitle}}` |

A run launched with `requesterEmail: "pat@example.com"` and `ticketTitle: "Printer offline"` sends one email to `pat@example.com` and one to `support-leads@example.com`, both with the subject `We received your ticket: Printer offline`. The requester does not need a Forge account. If the requester's address comes from a step instead, such as a ticket lookup, wire that output to a node input named `requester` and use `{{inputs.requester}}`.

### Notify by email

A workflow [notify node](https://docs.gloo.com/forge/build/compose-a-workflow.md) with **Email** among its channels sends from `notifications@forge.gloo.com` through this outbox, not from `forge@`.

* **Recipients are Forge people, never addresses.** The node records one email obligation per person it resolves (the run starter, the workflow owner, a person, or an org unit's members). The address is the person's own, read when the obligation is delivered, after the run and the recipient are checked again.
* **Off until an operator enables it.** Email is sent only when SendGrid is enabled on the notifications capability chain. Otherwise the email channel is skipped as `channel_disabled` when the node runs.
* **Satisfied at hand-off.** An obligation is satisfied once it is enqueued here under the key `obligation:<id>`; the outbox then owns delivery state and retries. A person with no email address, or a message the outbox rejects at enqueue, holds the obligation for attention instead.
* **Replies land on the run.** The subject is the node's title (or its name), and the tokenized sender names the run as the reply target.

## Limits

| Limit | Value |
| - | - |
| Inbound request body | 20 MiB, so attachments over **about 18 MB** in total are not supported |
| Stored body, inbound and outbound | 256 KiB each for `text` and `html`; a longer inbound body is cut and flagged |
| Inbound recipients kept | 100 in `to`, 100 in `cc` |
| Inbound multipart parts | 512 per post, form fields and attachments together |
| SendGrid Inbound Parse retries | Up to 3 days on any non-2xx answer |
| Inbound duplicate window | 7 days, by Message-ID |
| Inbound log retention | 30 days after receipt, every disposition, attachments included |
| Delivery retention | 30 days after a terminal row's last update |
| Route rate | 60 per minute by default, 600 maximum, burst of 10 |
| Outbound attempts | 5 (one send plus four retries) |

## Permissions

Email adds no permission keys. It reuses the webhook keys:

* `webhooks:read` — view senders, the inbound token's status, routes, the inbound log, and deliveries.
* `webhooks:manage` — create, rotate, pause, and resume the inbound token; create, edit, and delete routes.

Picking the workflow for a new `workflow` route in the console also reads the workflow catalog, which needs `workflows:read`. Without it the picker says so, and you can still create a `drop` route.

## Do it over the API

These calls use the `FORGE_BASE` set up in the Raw HTTP tab of the [quickstart](https://docs.gloo.com/forge/quickstart.md). These operations refuse an External App token: send a [Personal key](https://docs.gloo.com/forge/console/settings/personal-keys.md#choose-a-credential) or a platform API key as the bearer instead of the quickstart's `ACCESS_TOKEN`, with scopes that include `webhooks:manage` and `webhooks:read`. Creating a route checks the routed workflow's published version as a publish does: add `agents:use` when it runs agents and `credentials:use` when it binds a company's Credentials, and the key's owner must hold both where the workflow needs them. Create the inbound token in **Platform → Email**; the calls below add a route and confirm that mail reaches it.

Create a route that starts a workflow for mail to `help@forge.gloo.com`. `workflowVersionId` pins a published version, and `ratePerMinute` and `enabled` are optional:

```bash theme={null}
ROUTE_ID=$(curl -sS -X POST "$FORGE_BASE/api/v3/email-routes" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: email-route-help-v1" \
  -d "{\"localPart\": \"help\", \"kind\": \"workflow\", \"workflowId\": \"$WORKFLOW_ID\", \"senderPolicy\": \"dkim_pass\", \"orgUnitId\": \"$ORG_UNIT_ID\"}" \
  | jq -r '.data.routeId')
```

This needs `webhooks:manage`. Send a test message, then read the inbound log, which needs `webhooks:read`:

```bash theme={null}
curl -sS "$FORGE_BASE/api/v3/email-inbound?limit=15" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  | jq '.data[] | {messageId, disposition, dispositionReason, receivedAt}'
```

A `routed` row started a run; any other disposition names its reason in the [table above](#inbound-dispositions).

Over MCP, create the route with `forge_call_operation`:

```json theme={null}
{
  "operationId": "createEmailRouteAdmin",
  "input": { "localPart": "help", "kind": "workflow", "workflowId": "<workflow id>", "senderPolicy": "dkim_pass", "orgUnitId": "<org unit id>" },
  "idempotencyKey": "email-route-help-v1"
}
```

and read the inbound log with `forge_call_read_operation`:

```json theme={null}
{ "operationId": "listEmailInboundAdmin", "input": { "limit": 15 } }
```

## Related

* [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md) — the webhook ingress this transport sits beside
* [Approvals and HITL](https://docs.gloo.com/forge/run/approvals-and-hitl.md) — holds, and the other surfaces that resolve them
* [Slack in production](https://docs.gloo.com/forge/run/slack.md) — the other human-interaction transport
* [Emergency stops](https://docs.gloo.com/forge/run/trust-fabric.md#emergency-stops) — the platform stop that makes inbound answer `500`

## Workflow delivery certainty

For workflow-owned mail, the outbox records uncertainty before the provider request. A lost
acknowledgement or ambiguous server response cannot authorize automatic resend. A positive
accepted or delivered receipt is preserved across later bounce/drop events. Operator repair requires
proof that the original request was not applied and creates a separate delivery obligation.

An explicit Publish/Notify confirmation policy distinguishes durable queueing, provider acceptance,
and final delivery. Notify obligation satisfaction records outbox hand-off, not provider acceptance.
Final delivery requires a verified locally ingested delivery event before the original deadline; an
earlier provider timestamp cannot backdate a late receipt. The workflow can route confirmation
failures to an error handler while retaining the technical failure and original effect certainty.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.