# 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 after a workspace key is available. - Human page: https://mailrith.com/developers/agents - Markdown page: https://mailrith.com/developers/agents.md - Category: Getting Started - Reading time: 6 min read - Last updated: 2026-07-13 - Related keywords: Agents, Agents developer docs, Getting Started, Getting Started developer docs, Mailrith developer docs, Mailrith public API, Use a Deterministic Discovery Flow, Machine-Readable Entry Points, Current Agent-Safe Tasks, SDKs, MCP Server, API Reference ## 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 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 instead of guessing the API 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. Use this order: 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 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 action it needs to perform. 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 API 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 you decide which tools the agent may call. ## Machine-Readable Entry Points Mailrith publishes human-readable and machine-readable entry points. Use the lighter files for orientation. Use 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 returns 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` API supports practical agent work, but you should limit each agent to the tools needed for its 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, require explicit approval in the agent runtime before destructive or high-impact actions. 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 job updates through signed developer webhooks or deliberate polling. - Restrict live-send and delete tools unless the user has clearly approved those actions. 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 powers 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 and includes 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 the API reference to find exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.