Skip to content

AgentMail MCP and WebSocket setup

This runbook prepares AgentMail as the email intake transport. It does not authorize an account, create a mailbox, or connect the application.

Security boundary

  • Keep AGENTMAIL_API_KEY in the approved secret store only. Never place its value in appsettings, a manifest, a transcript, Jira, Confluence, or Slack.
  • Use a dedicated mailbox such as FOUNDER_INTAKE_AGENTMAIL_ADDRESS; do not reuse a personal mailbox.
  • Grant the integration access to that mailbox only. Do not authorize organization-wide mail access unless a separately approved later phase requires it.
  • Treat inbound email as untrusted. The broker must validate the sender against the pilot allowlist and preserve the message ID for idempotency.
  • The current FLT-75 implementation is dry-run and must not start an agent or create work outside the approved Jira/Confluence adapters.

MCP connection

  1. Create the dedicated AgentMail mailbox and record its address in the secret/configuration system as FOUNDER_INTAKE_AGENTMAIL_ADDRESS.
  2. Create a narrowly scoped AgentMail API credential for that mailbox and store it as AGENTMAIL_API_KEY.
  3. Add the AgentMail MCP server URL as AGENTMAIL_MCP_SERVER_URL in the deployment configuration. Obtain the exact URL and supported tool names from the authenticated AgentMail documentation; do not guess or hard-code an endpoint.
  4. Configure the MCP client with the API credential through its secret reference, not an inline header value. Allow only the tools needed to read a new message, retrieve its metadata/body, and send an acknowledgement if the pilot requires it.
  5. Run a read-only connection check against the dedicated mailbox. Confirm the service identity cannot list or read any unrelated mailbox.

WebSocket event path

  1. Register an inbox/message-received subscription for the dedicated mailbox only.
  2. Store the subscription endpoint as AGENTMAIL_WEBSOCKET_URL; store any signing secret or subscription credential under the provider-issued secret name in the approved secret store.
  3. Require encrypted transport, validate the provider's event signature before parsing, and reject events that lack a stable message/event ID.
  4. Deduplicate on the provider event ID and email message ID before creating an intake record. A reconnect can replay events.
  5. Keep the WebSocket consumer passive: it may enqueue an intake event, but it must not execute work or bypass the FLT-80 dispatch gate.

Operational checks

  • Verify a test email from an allowlisted pilot sender reaches the broker once and produces a dry-run intake record.
  • Verify an unallowlisted sender and a malformed/signature-invalid event are rejected without exposing their content to Slack, Jira, or Confluence.
  • Verify revoking AGENTMAIL_API_KEY stops mailbox access and that the rollback checklist can disable the consumer without deleting evidence.