This document scopes the Email Gateway feature inside Agent Vault: an in-binary email gateway that gives every internal tool, and every AI agent running alongside them, one allowlisted, audited path for transactional mail. It runs as its own Agent Vault instance dedicated to email, with an instance-level setting that hides the feature entirely on any vault deployment that doesn't enable it. Everything below is built fresh inside the fork's custom-feature area — SMTP ingress, the gateway HTTP surface, the canonical mapping layer, the MailerQ proxy, the CloudAMQP outbox, and the event consumers. Auth, audit, the UI shell, and the agent proxy come from Agent Vault itself.
Email Gateway is a feature inside Agent Vault. Internal tools and AI agents both call one HTTP endpoint to send mail. The vault authenticates each caller (SMTP credentials, API key, or both depending on path), enforces per-tenant rules (allowed sender domains, validation, rate limiting), maps source-specific payloads from Sendy, Odoo, and similar services into the canonical MailerQ envelope, then either proxies to MailerQ or publishes to a CloudAMQP outbox queue. Delivery success and failure events flow back through dedicated queues into an email events processor. An instance-level setting lets any other vault deployment keep the feature off so it doesn't appear in the proxy or the UI. Auth, sessions, credentials, audit, alerts, and the operator UI shell come from Agent Vault. Everything else — SMTP ingress, the gateway HTTP surface, the policy and validation layer, the canonical mapping, the MailerQ proxy, the CloudAMQP outbox, the event consumers, the new schema, and the instance toggle — is new code in the fork's custom-feature area.
Four pressures converge here. Internal tools each ship their own email plumbing, which makes outages and deliverability everyone's problem. AI agents are coming online next to those tools and need a controlled send path. A standalone Musth-Mail-Gateway service would mean rebuilding auth, credentials, and audit that Agent Vault already provides. Email runs on its own dedicated instance, with a clean off-switch on every other deployment.
One vault binary, one deploy story, one set of operators. Every internal tool and every agent uses the same allowlist, the same audit log, the same alerting. Two perimeters becomes one.
Today, every tool talks to its own SMTP setup, so a misconfigured sender or a runaway agent can land us on a blocklist. Centralising the send path lets us enforce sender domains, rate limits, and content rules before mail leaves the perimeter.
Auth, sessions, credentials, encrypted config, audit, alerts, the operator UI shell, and the agent proxy are all shipped by Agent Vault. The email gateway plugs straight into those primitives. A separate Musth-Mail-Gateway service would mean duplicating every one of them, plus a second deploy, a second on-call, and a second auth perimeter. That reuse is the core of why this lives inside the vault binary.
A separate Agent Vault instance is scoped to email so credential ops, bounce traffic, and the inbound SMTP port don't share blast radius with our credential vaults. Other instances stay clean: an instance setting hides the feature from the proxy and the UI entirely.
Three audiences, three experiences. The primary user is internal tooling; AI agents share the same path; operators run it from the existing vault UI.
Agents authenticate through the same gateway with their own API key issued from the vault, scoped to send and (optionally) MailerQ ops. Approval thresholds and rate ceilings live alongside the existing agent policy in the vault UI. Nothing custom on the agent side.
The existing Agent Vault operator UI grows new tabs for send log, allowed sender domains, API keys, MailerQ proxy operations, and CloudAMQP queue health. Login, sidebar, header, audit, and alerts are unchanged.
A single new package inside the vault binary, deployed as its own Agent Vault instance. Other instances ship the same binary with the feature switched off. The full technical walkthrough lives on the build guide; this is the scope-level view.
Custom code under internal/custom/email/ and web/src/custom/email/. Zero edits to upstream files in this scope.
SMTP ingress, gateway HTTP surface, mapping, MailerQ proxy, CloudAMQP outbox, event consumers, and the new schema all live under internal/custom/email/ and web/src/custom/email/.
One Agent Vault binary, deployed as a dedicated email instance. No separate service to operate or upgrade.
Instance flag AGENT_VAULT_CUSTOM_EMAILGATEWAY_ENABLED=false on every other deployment. Routes 404, UI tabs hidden, proxy passes through.
Everything on the left is already shipped by the Agent Vault product and used as-is. Everything on the right is new code in the fork's custom-feature area for this scope.
Sized S / M / L by code surface and unknowns, not calendar weeks.
Custom feature package scaffolded under internal/custom/email/ and web/src/custom/email/. New tables created: smtp_relay_users, smtp_relay_logs, smtp_relay_api_keys, mailerq_ip_pools. UI shell tabs hidden behind AGENT_VAULT_CUSTOM_EMAILGATEWAY_ENABLED. No live traffic.
API key auth wired in. Canonical message format validation. Allowed sender domain enforcement in runtime. Mapping layer for Sendy and Odoo payloads. MailerQ proxy with allowlisted operations. CloudAMQP outbox publisher. End-to-end through MailerQ in shadow mode behind _LIVE_SEND_ENABLED=false.
Success and failure queue consumers. Email events processor service. Correlation id end-to-end from request through to delivered / bounced. Operator UI: send log, mapping inspector, event timeline.
The mapping layer must produce a message in this structure. Field names match the MailerQ JSON envelope format. Three groups: top-level, tracking, and MIME.
| Field | Type | Required | Notes |
|---|---|---|---|
| recipient | String | Required | Envelope RCPT TO address. |
| envelope | String | Optional | Envelope MAIL FROM. Defaults to from address. |
| priority | Integer | Optional | Higher = higher priority. Default resolved from the vault's default_priority setting if absent. |
| ips | Array | Optional | Sending IP addresses. If absent, resolve via mailerq_ip_pools using the from-address domain. |
| tags | Array | Optional | String labels for filtering and reporting. |
| campaign_id | String | Optional | Campaign identifier for tracking. |
| Field | Type | Notes |
|---|---|---|
| tracking.userId | String | — |
| tracking.endpointId | String | — |
| tracking.context | String | — |
| tracking.visible | Boolean | — |
| Field | Type | Required | Notes |
|---|---|---|---|
| mime.to | String | Required | Same as recipient. |
| mime.from.address | String | Required | From header address. |
| mime.from.name | String | Optional | Defaults to from address. |
| mime.replyto.name | String | Optional | Defaults to from name. |
| mime.replyto.address | String | Optional | Defaults to from address. |
| mime.subject | String | Optional | — |
| mime.text | String | Conditional | Required if no HTML content block. |
| mime.content | Array | Conditional | Required if no text. Each block: type: "html", content field. |
| Header |
|---|
| mime.headers.List-Unsubscribe |
| mime.headers.List-Unsubscribe-Post |
| mime.headers.Feedback-ID |
No defaults are baked into the mapping layer or the runtime. Every tunable below is configured per vault (or per setup, where it makes sense) and resolved at request time from the vault that the authenticated caller belongs to.
Per-vault settings persist in the vault's own settings store. The mapping layer and runtime always read the configured value for the authenticated caller's vault — never a literal in code. Empty / unset values fall through to the instance-level default declared in environment configuration, not to a hard-coded constant.
These are infrastructure connection details, not behaviour knobs. They live in environment variables or deployment secrets on the email instance — never in the database, never in the per-vault settings UI.
Only the items above stay in env. Instance enable flag is AGENT_VAULT_CUSTOM_EMAILGATEWAY_ENABLED
Everything that controls send behaviour — priority defaults, allowed sender domains, IP pool strategy, rate limits, approval thresholds, auth mode, live-send toggle — lives in the per-vault settings UI above, not here. Env values only act as the instance-level fallback when a vault setting is unset.
None are blockers. Each has a mitigation built into the plan.
Sender domains enforced against allowed_sender_domains. IP pools resolved per from-domain through mailerq_ip_pools. Bounce traffic isolated on the dedicated email instance.
Per-key rate limits enforced before publish. Approval thresholds reuse the existing agent policy surface. Failure queue backlog triggers operator alert.
Dedicated Agent Vault instance for email. Instance setting hides the feature entirely on every other deployment. Inbound SMTP behind a sub-flag.
Zero edits to upstream files in this scope. All new code lives under internal/custom/ and web/src/custom/. Upstream syncs continue to flow through the existing release-to-staging workflow.
Outbox publish has retry and failure handling defined. Queue connectivity surfaced through gateway health checks. Shadow mode runs end-to-end before live send.
Not how this lands. Two env flags — enable and live-send — run shadow first, then flip one vault at a time. Anything goes wrong, flip back.
Five actor types, five surfaces. Every cell shows the auth method and what's allowed. Auth, sessions, and the user model all come from Agent Vault. The gateway adds the new SMTP, API key, and scope checks on top.
| Actor → Surface ↓ |
Internal tool (SMTP) | Internal tool / AI agent (API) | Operator | Vault owner | External tenant |
|---|---|---|---|---|---|
|
SMTP ingress
New SMTP listener in the custom area.
|
Yes SMTP credentials from smtp_relay_users. |
N/A HTTP services hit the API instead. |
No | No | No |
|
HTTP gateway endpoints
Send + map paths.
|
Optional If a path declares it, SMTP creds accepted alongside API key. |
Yes API key from smtp_relay_api_keys, scoped. |
Diagnostics Operator API key issued from the vault. |
No | No |
|
MailerQ proxy
Allowlisted operations only.
|
No | Scoped API key with the MailerQ-operations scope. |
Read Operator UI surfaces approved ops. |
Full Owner-level access through vault UI. |
No |
|
CloudAMQP outbox
Publish side.
|
Via SMTP SMTP path can land in the outbox. |
Yes API key with the CloudAMQP-operations scope. |
Read Queue health in operator UI. |
Full Owner can drain / requeue. |
No |
|
Instance settings
Enable and live-send flags.
|
No | No | No | Yes Only the vault owner toggles the feature. |
No |
Wireframe sketches, not final designs. Every screen lives inside the existing Agent Vault UI shell; this section shows the new surfaces the email feature introduces. The first row is the operator and owner surfaces inside the dedicated email instance. The second row is what tenant vaults and the instance owner see. Everything else (login, sidebar, header, audit, alerts) is unchanged.
Five steps, in order. The build lives entirely inside the fork's custom-feature area, ships through the existing staging → main flow, and never edits an upstream file.
Single tracking issue under the existing parent. Links the build guide, this scope page, and the touch-point table for custom paths.
Create internal/custom/email/ and web/src/custom/email/. Wire through internal/server/custom_wiring.go → initCustom. Migrations for the new tables (smtp_relay_users, smtp_relay_logs, smtp_relay_api_keys, mailerq_ip_pools).
Foundation → core send path → events + UI. Each PR lands behind AGENT_VAULT_CUSTOM_EMAILGATEWAY_ENABLED and the live-send sub-flag.
The existing release-to-staging workflow continues. Custom-aware sync review catches any touch-point drift before merge to staging.
Run shadow mode end-to-end. Flip _LIVE_SEND_ENABLED one tenant at a time, watch the success queue, expand from there.