# 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: AI Agent Platform - Reading time: 6 min read - Last updated: 2026-07-22 - Related keywords: Agents, Agents developer docs, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Use a Deterministic Discovery Flow, Machine-Readable Entry Points, Current Agent-Safe Tasks, Use Starting Points And Secure Handoffs, Authorize And Execute Workspace Changes, 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 right now. 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. Mailrith checks these entry points after deployments and every five minutes. Read `/.well-known/agent-status.json` for the current contract version, monitored services, and monitoring link. 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. Read `https://mailrith.com/.well-known/agent-status.json` for the monitored API and MCP entry points. 5. Call `GET /v1` to confirm the API version metadata. 6. Load `GET /v1/openapi.json` so the agent has exact request and response schemas. 7. Create or provide a workspace API key only after the agent knows what action it needs to perform. 8. Call `GET /v1/capabilities` with that key to confirm workspace-specific access. 9. 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/agent-status.json`, `/.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 monitored status. `GET /v1` is a compact version metadata endpoint. `GET /v1/openapi.json` is the full schema contract. `GET /v1/capabilities` is authenticated and returns only operations currently available to the key and workspace. Capability discovery accounts for the credential's Permissions, the current plan, workspace limits, email delivery readiness, and rollout state. When a workspace prerequisite blocks an otherwise authorized operation, `limitations` explains what is missing and can include a setup link. **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/agent-status.json 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 the Broadcasts Work Profile or `broadcasts:write`. Mailrith supports Subscriber sync, Form and Segment inspection, Broadcast, Sequence, and Automation management, secure Email Delivery Connection setup, webhook subscriptions, and async import or export orchestration through public operations. Mailrith uses API key and OAuth resource permissions as the authorization boundary. A write permission covers every public write operation for that resource. Bulk Subscriber import and export remain separate permissions because they move large datasets. - Inspect the authenticated workspace, subscribers, tags, custom fields, segments, forms, and landing pages. - Search MCP operations with ordinary task language, then load the exact schema for the selected operation. - List canonical email, Form, and Landing Page starting-point metadata, load one full starting point on demand, and create the matching workspace object by ID. - Create and manage drafts or definitions for email templates, sequences, automations, magic links, broadcasts, and webhook subscriptions. - Start a short-lived Email Delivery Connection setup, let the signed-in user enter provider credentials in Mailrith, check pending, failed, completed, or expired status, and renew an incomplete link without rebuilding its non-secret context. - Queue subscriber import and export jobs, then react to job updates through signed developer webhooks or deliberate polling. - Grant only the resources a workflow needs, then confirm results from the changed resource or progress endpoint. 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. ## Use Starting Points And Secure Handoffs Starting points let an agent begin with the same approved designs that people see in Mailrith. List starting points first because list responses contain only compact metadata. Load one item only after choosing it, then create the email template, Form, or Landing Page with `starting_point_id`. Email delivery credentials remain human-entered. Start a setup session, open `setup_url` for the signed-in Mailrith user, and poll the session ID at a deliberate interval. After the link opens, Mailrith uses a browser-bound secure session so the user can reload or restart an expired page without sending provider credentials through the agent. A completed response includes the connection ID. Setup status is kept for a bounded time in short-lived storage. Mailrith does not create a permanent handoff history or copy provider secrets into API responses. 1. List metadata from the matching `/v1/starting-points/...` collection. 2. Choose one starting point by its ID and load its item endpoint only when full content is needed. 3. Create the workspace object with `starting_point_id` and its required name or slug. 4. For email delivery, create a setup session and send `setup_url` to the signed-in user. 5. Check the setup session at a bounded interval until it is completed, failed, or `expires_at` has passed. Do not poll continuously. 6. If an incomplete session expires, call its `renew` operation to issue a fresh link with the same non-secret defaults. ## Authorize And Execute Workspace Changes A scoped API key or OAuth access token can call an operation directly when its Permissions include the operation's required scope. Mailrith does not add a separate per-action approval step. Use a distinct credential for each workflow, grant only the required scopes, and revoke the credential when the workflow should no longer have access. Before a Broadcast send, use the preflight endpoint and resolve every blocking issue. Supply an idempotency key for operations that support it. Reuse the same key only for the same logical request. Use the returned request ID, current resource, and progress endpoint when you need to confirm an uncertain result. 1. Choose the narrow Work Profile or resource permission required by the workflow. 2. Create a task-specific API key or complete OAuth with that Work Profile. 3. Run capability discovery and confirm the operation is available. 4. Run the documented preflight check when the operation provides one. 5. Call the operation directly and include an idempotency key when supported. 6. Use the request ID and current resource state to confirm the result before retrying an uncertain mutation. > A granted scope authorizes the operation. Keep credential scope narrow instead of adding a second approval queue after authorization. **Delete With A Scoped Credential** ```bash curl -X DELETE "https://api.mailrith.com/v1/custom-fields/cf_company" \ -H "Authorization: Bearer $MAILRITH_API_KEY" ``` **Preflight And Send A Broadcast** ```bash curl "https://api.mailrith.com/v1/broadcasts/broadcast_example/preflight" \ -H "Authorization: Bearer $MAILRITH_API_KEY" curl -X POST "https://api.mailrith.com/v1/broadcasts/broadcast_example/send" \ -H "Authorization: Bearer $MAILRITH_API_KEY" \ -H "Idempotency-Key: send-broadcast-example-1" ``` ## 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.