Integrations · Email

Email inbound webhookAccepts SendGrid / Mailgun / Postmark forwarded inbound.

What this is

Receives forwarded emails as JSON (Postmark / generic) or form-data (SendGrid Inbound Parse / Mailgun Routes), normalizes them, and drops the body into the inbox.

What to do

POST to POST /api/integrations/email. Each email creates an InboxItem (rawText = sender + subject + body, documentText = full normalized payload) and queues TRIAGE_INBOX.

What happens next

Inbox shows the email; the worker triages on its next tick. Outbound SMTP is roadmap — drafts still sit as approval items.

Inbound

Active

Accepting unsigned posts (fine for local dev). Set the signing secret below to require HMAC.

Outbound

Optional

Add a webhook URL or bot token below to receive approval notifications.

Try it now

# (no signing — EMAIL_WEBHOOK_SECRET is not set)
curl -X POST https://hermes-agent.vercel.app/api/integrations/email \
  -H "Content-Type: application/json" \
  -d '{"from":"alex@example.com","to":"foundry@yours","subject":"Refund","text":"Help me dispute order #A4827."}'

# Mailgun-style form-data also works:
curl -X POST https://hermes-agent.vercel.app/api/integrations/email \
  -F sender=alex@example.com \
  -F recipient=foundry@yours \
  -F subject="Refund" \
  -F body-plain="Help me dispute order #A4827."

On success the response includes inboxItemId; the item appears in /inbox and a TRIAGE_INBOX job is queued for the worker.

Forwarding setup

SendGrid Inbound Parse: point a domain's MX records at SendGrid, configure parse to POST https://hermes-agent.vercel.app/api/integrations/email.
Mailgun Routes: create a route with action forward("https://hermes-agent.vercel.app/api/integrations/email").
Postmark Inbound: enable inbound on a server, set the inbound webhook URL to https://hermes-agent.vercel.app/api/integrations/email.
For all three, optionally front the route with a small shim that re-signs the body using EMAIL_WEBHOOK_SECRET.

Recent inbound

Nothing yet. Run the test command above and refresh.

Developer detailsShow env vars + signing

Environment variables

EMAIL_WEBHOOK_SECREToptionalWhen set, inbound POSTs must include a constant-time HMAC-SHA256 of the raw body in `X-Foundry-Email-Signature: sha256=<hex>`. Useful when fronting the route with a tiny signing shim.

Secrets are read from process.env only. They are never logged or shown anywhere in the UI.