# Agents > Mailrith exposes a compact discovery stack for AI agents: llms files on the marketing site, version metadata on the API root, the versioned OpenAPI contract, authenticated capability discovery, and official SDK and MCP entry points once a workspace key is available. - Human page: https://mailrith.com/developers/agents - Category: Getting Started - Reading time: 6 min read ## What this guide covers Discover Mailrith from agent runtimes with llms files, API metadata, OpenAPI, and authenticated capability discovery. ## Use a Deterministic Discovery Flow Configure AI agents and automation runtimes to discover Mailrith's current public API surface instead of guessing the shape from memory. Start with unauthenticated discovery so the runtime can learn what Mailrith exposes without a secret. After a workspace API key is available, call authenticated capability discovery so the agent knows exactly what the key can do in that workspace. The recommended order is: read `llms.txt`, inspect `/.well-known/api-catalog`, inspect `GET /v1`, load `GET /v1/openapi.json`, then call `GET /v1/capabilities` with the target workspace key before choosing REST, an official SDK, or the MCP server. 1. Read `https://mailrith.com/llms.txt` for the compact integration index. 2. Read `https://mailrith.com/llms-full.txt` when the agent needs more detailed workflow guidance. 3. Read `https://mailrith.com/.well-known/api-catalog` when the runtime supports well-known API discovery. 4. Call `GET /v1` to confirm the API version metadata. 5. Load `GET /v1/openapi.json` so the agent has exact request and response schemas. 6. Create or provide a workspace API key only after the agent knows what it needs to do. 7. Call `GET /v1/capabilities` with that key to confirm workspace-specific access. 8. Choose REST, [SDKs](https://mailrith.com/developers/sdks.md), or [MCP Server](https://mailrith.com/developers/mcp.md) based on the runtime and risk level. - Read `/llms.txt` for the compact agent-oriented index. - Read `/llms-full.txt` when the agent needs workflow guidance and current public-surface boundaries. - Use `/.well-known/api-catalog`, `/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`, and `/.well-known/mcp/server-card.json` when an agent platform discovers integrations from the marketing domain. - Call `/v1/capabilities` after authentication to confirm the resource operations currently available to the key. - Prefer capability discovery over a hard-coded allowlist when deciding which tools the agent may call. ## Machine-Readable Entry Points Mailrith publishes both human-readable and machine-readable entry points. Use the lighter files for orientation and the OpenAPI document when the integration needs exact request and response schemas. `/.well-known/api-catalog` points agents from the marketing site to the API contract, docs, and health endpoint. `GET /v1` is a compact version metadata endpoint. `GET /v1/openapi.json` is the full schema contract. `GET /v1/capabilities` is authenticated and reflects the permissions available to the key being used. **Unauthenticated Discovery** ```bash curl https://mailrith.com/llms.txt curl https://mailrith.com/llms-full.txt curl https://mailrith.com/.well-known/api-catalog curl https://mailrith.com/.well-known/mcp/server-card.json curl https://api.mailrith.com/v1 curl https://api.mailrith.com/v1/openapi.json ``` **Authenticated Capability Discovery** ```bash curl https://api.mailrith.com/v1/capabilities \ -H "Authorization: Bearer mrk_example_secret_key" ``` ## Current Agent-Safe Tasks The current public `/v1` surface is broad enough for practical agent work, but keep agents constrained to the tools needed for the task. A subscriber-reporting agent does not need permission to send broadcasts. Mailrith supports subscriber sync, form and segment inspection, campaign and automation draft management, webhook subscriptions, and async import or export orchestration through public operations. For agent workflows, keep destructive or high-impact actions behind explicit approval in the agent runtime. Creating a draft is low risk. Sending a broadcast, deleting a form, or changing automation definitions is higher risk. - Inspect the authenticated workspace, subscribers, tags, custom fields, segments, forms, and landing pages. - Create and manage drafts or definitions for email templates, sequences, automations, magic links, broadcasts, and webhook subscriptions. - Queue subscriber import and export jobs, then react to updates through signed developer webhooks or deliberate polling. - Restrict live-send and delete tools unless the user has clearly approved that behavior. Related OpenAPI operation groups: - Workspace - Subscribers - Tags - Custom Fields - Email Templates - Forms - Sequences - Automations - Magic Links - Broadcasts - Segments - Webhook Subscriptions - Jobs > For agent integrations, prefer the official TypeScript SDK, Python SDK, or Mailrith MCP server. The raw REST API remains available when you need lower-level control. ## Related Guides - [SDKs](https://mailrith.com/developers/sdks.md): Mailrith ships official TypeScript and Python SDKs generated from the same public contract that drives the OpenAPI document and capability map. - [MCP Server](https://mailrith.com/developers/mcp.md): Mailrith's official MCP server is the highest-level interface for agent runtimes. This page covers the remote endpoint plus copy-paste examples for OpenAI, Claude, n8n, and Pipedream. - [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.