Agents

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 OAuth or a workspace API key is available, call authenticated capability discovery so the agent knows exactly what the credential 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 credential 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.

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 credential in its 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.

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.

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.

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.