# AI Agent Architecture And Security > Mailrith uses one public resource model, least-privilege credentials, typed operations, existing delivery safeguards, request IDs, and current-resource verification across every supported agent client. - Human page: https://mailrith.com/developers/agent-security - Markdown page: https://mailrith.com/developers/agent-security.md - Category: AI Agent Platform - Reading time: 10 min read - Last updated: 2026-08-24 - Related keywords: AI Agent Architecture And Security, AI Agent Architecture And Security developer docs, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Architecture And Trust Boundaries, Permissions And Authentication, Security And Data Handling, Result Verification, Troubleshooting, AI Agent Quickstarts, AI Agent Client Compatibility, Authentication ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## What This Guide Covers Understand Mailrith's agent architecture, trust boundaries, permissions, OAuth, result verification, and troubleshooting flow. ## Architecture And Trust Boundaries Mailrith keeps one public resource model across REST, the generated SDKs, CLI, and MCP tools. Machine-readable discovery describes the same operations; it does not add an agent-only write or delivery path. Treat the model and agent runtime as untrusted input. OAuth or a workspace API key establishes the connection, workspace permissions limit available operations, typed schemas validate input, and existing Mailrith domain services enforce Subscriber, sender, provider, preflight, and delivery rules. API key and OAuth scopes are the authorization boundary. Request IDs correlate API responses without creating a second copy of Subscriber payloads, message bodies, or secrets. - Discovery: llms files, API catalog, API version, OpenAPI, capabilities, MCP server card, and Agent Skill. - Connection: OAuth with resource binding for user-connected clients; narrow workspace API keys for trusted server-side jobs. - Operation: typed REST or MCP tools call the existing Subscriber, Broadcast, Sequence, Automation, capture, and delivery services. - Control: narrow scopes, typed schemas, idempotency, revocation, preflight, and internal emergency controls. - Observation: request IDs for every request, plus current resources, progress, and final outcomes for workspace changes. ## Permissions And Authentication Use OAuth when a person connects Mailrith to OpenAI, Claude, Codex, or another user-facing client. The authorization flow uses PKCE, exact redirect validation, state checking, resource binding, refresh-token rotation, and revocation. Use an API key only in a trusted server-side runtime. Create one key per integration, use Full Email Marketing Access for a general-purpose agent or a focused Work Profile for a narrower integration, set an expiration, and rotate or revoke that key without affecting other connections. 1. Call capability discovery with the credential before selecting tools. 2. Compare required operation scopes with the granted workspace permissions. 3. Expose a small client tool allowlist. Do not rely on a prompt to prevent disallowed calls. 4. Revoke a connection immediately if its owner, runtime, callback address, or task changes unexpectedly. ## Security And Data Handling Never put API keys, OAuth tokens, Subscriber exports, or full email bodies in prompts, URLs, traces, screenshots, or logs. Store credentials in the client secret store and pass them only in authorization headers. Mailrith keeps detailed content in its normal workspace resource instead of copying it into a separate agent history. Provider-side tool confirmation is optional and does not expand Mailrith Permissions. A compromised client cannot expand the scopes on its existing credential. ## Result Verification Start an investigation with the request ID returned by Mailrith. Read the target resource or progress endpoint to confirm its current state. If an outcome is uncertain, inspect the target and progress endpoint before retrying. Repeating a mutating operation without checking can create a second logical action even when the first request reached Mailrith. 1. Revoke the connection if compromise is possible. 2. Record the request ID, connection, operation, target resource, and time range. 3. Review the target resource's current state. 4. Check delivery progress or job status when the operation is asynchronous. 5. Retry only after the current resource or progress state confirms that the original operation did not complete. ## Troubleshooting For connection failures, check the server URL, OAuth callback, token expiration, resource binding, and requested scopes. The submitted catalog stays fixed, so check client allowlists when a tool is missing and check the connection permissions when a listed tool cannot run. For a denied operation, read the stable error code and request ID. Do not retry validation, Permission, resource-conflict, or preflight errors without changing the cause. - `401`: reconnect or rotate the credential; do not repeat the secret in logs. - `403`: request the missing task permission from a workspace owner or remove the operation. - `409`: inspect idempotency, current resource state, or an uncertain outcome before retrying. - `422`: correct the typed input or blocking preflight issue. - `429` or a temporary `5xx`: honor retry guidance and keep pagination and polling bounded. ## Related Guides - [AI Agent Quickstarts](https://mailrith.com/developers/agent-quickstarts.md): Start with the Mailrith plugin, the Mailrith Connector, or a scoped MCP connection. Then follow task-based paths for read-only, Broadcast, Sequence, and safe test-workspace workflows. - [AI Agent Client Compatibility](https://mailrith.com/developers/agent-compatibility.md): The Mailrith plugin is available for ChatGPT and Codex, and the Mailrith Connector is available for Claude. Both use OAuth, while other supported clients can use scoped MCP connections. - [Authentication](https://mailrith.com/developers/authentication.md): Every protected `v1` request is authorized through a workspace-scoped API key. This page covers the required header shape, workspace scoping behavior, and authentication failure handling.