Skip to main content
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. 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. 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.
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.
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. Mail to a local part with no enabled route is logged unrouted and answered 200, so SendGrid does not retry it.
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

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. 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. 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), 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. 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. 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.
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

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

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. These operations refuse an External App token: send a Personal key 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:
This needs webhooks:manage. Send a test message, then read the inbound log, which needs webhooks:read:
A routed row started a run; any other disposition names its reason in the table above. Over MCP, create the route with forge_call_operation:
and read the inbound log with forge_call_read_operation:

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.