Architecture

Angelos has a small, account-specific server boundary. A deployment has one configured mailbox and an explicit list of OAuth subjects allowed to access it. Multiple allowed subjects share that same mailbox; they are not separate tenants.

Request path

1. The MCP client obtains an access token from the configured external issuer.
2. The authentication middleware verifies the JWT, owner allowlist, audience, and base mail.read scope.
3. A typed MCP tool validates its input and checks the operation’s scope and deployment gate.
4. The mail backend opens a bounded TLS connection to the configured IMAP or SMTP server.
5. The result returns structured data, warnings, or an error to the client.

The official Go MCP SDK handles stateless Streamable HTTP with JSON responses. An MCP session is not a durable transaction or approval record. The mailbox remains the provider’s source of truth.

Packages

Package	Responsibility
internal/auth	Protected-resource metadata, token verification, public signing-key cache, and scope checks
internal/config	Administrator-configured mailbox credentials and TLS endpoints
internal/mail	IMAP reads and guarded mutations, MIME parsing, and SMTP transport
internal/compose	Validated recipient envelope, MIME construction, and immutable content digest
internal/dispatch	Durable preparation, atomic send claim, and outcome recording
internal/app	MCP tool names, schemas, annotations, and operation boundaries

The root Go service is independent of the static docs/ workspace. Documentation builds need no mailbox access.

State

• Mail and folder state live at the IMAP provider.
• Credentials live in the API environment.
• Public issuer signing keys have a bounded in-memory cache.
• Prepared sends and dispatch records live in an optional external Redis REST store.

Sending is disabled without that store. Mailbox reads and ordinary mailbox writes do not require it. A function instance’s memory is never used as the sole duplicate-send guard.

Deliberate boundaries

Tools cannot choose arbitrary mail hosts or supply credentials. OAuth access to Angelos and the backend’s mailbox login are separate credentials with separate purposes.

UIDVALIDITY guards against stale message identity. Conditional flag updates use CONDSTORE where supported. Other clients can still modify the account concurrently; there is no global mailbox lock or cross-protocol transaction.

The trusted MCP client handles human confirmation. An exact payload digest ensures consistency between preparation and dispatch, while the durable claim limits a preparation to one dispatch attempt. Neither mechanism guarantees final delivery or proves human consent. See Safety and concurrency.