# AI Agent Quickstarts > 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. - Human page: https://mailrith.com/developers/agent-quickstarts - Markdown page: https://mailrith.com/developers/agent-quickstarts.md - Category: AI Agent Platform - Reading time: 12 min read - Last updated: 2026-08-25 - Related keywords: AI Agent Quickstarts, AI Agent Quickstarts developer docs, Mailrith AI Agent quickstart, Mailrith ChatGPT plugin setup, Mailrith Codex plugin setup, Mailrith Claude Connector setup, Mailrith MCP quickstart, AI Agent Platform, AI Agent Platform developer docs, Mailrith developer docs, Mailrith public API, Start Without A Sales Call, Use The Official Mailrith CLI, Choose One Task And One Client, Five-Minute Read-Only Quickstart, Broadcasts Quickstart, Live-Send Quickstart, Sequences And Operations Quickstart, Test Workspace Tutorial, Agents, AI Agent Architecture And Security, MCP Server ## 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 Connect Mailrith from ChatGPT, Codex, Claude, or another AI client, then test read-only and task-specific workflows in a dedicated workspace. ## Start Without A Sales Call Mailrith has self-serve signup, self-serve workspace API keys, and public API and MCP discovery. The Pricing page shows the current trial length and whether a credit card is required. You do not need a sales call to test an integration. Use a separate workspace with test-only data to keep experiments away from customer data. This is not a sandbox. Every saved change is real, and any permitted send or activation action can reach external systems or email addresses. 1. Open [Pricing](https://mailrith.com/pricing.md), choose a plan, and follow the trial or checkout option currently shown. 2. Create or select a workspace that you will use only for testing. 3. Open `Settings`, choose `API Keys`, and create a key with the smallest Work Profile that fits the test. 4. Read the public [OpenAPI contract](https://mailrith.com/openapi.json) or connect to the canonical MCP endpoint at `https://api.mailrith.com/mcp`. The `https://mailrith.com/.well-known/mcp` address is a discovery alias. 5. Keep real Subscribers and live-send tools out of the test workspace until the workflow has been reviewed. ## Use The Official Mailrith CLI The public [`@mailrith/cli`](https://www.npmjs.com/package/@mailrith/cli) package is the official Mailrith command-line tool for terminals and non-interactive agent runtimes. Operation search and schema inspection work without a credential. Sign in only when a command needs to read or change a Mailrith workspace. Use browser sign-in only from a local terminal where the browser returns to the same computer. For a remote or non-interactive agent, create a workspace API key with the smallest Work Profile needed, store it in the runtime's secret settings as MAILRITH_API_KEY, and run the CLI normally. The CLI reads that setting directly, so do not use browser sign-in. Never put an API key in a prompt, chat message, command, source file, screenshot, or log. **Inspect The CLI And Search Operations** ```bash npx @mailrith/cli@latest --help npx @mailrith/cli@latest operations search "schedule the newsletter" --json npx @mailrith/cli@latest operations describe scheduleBroadcast --json ``` **Sign In From A Local Terminal** ```bash npx @mailrith/cli@latest auth login npx @mailrith/cli@latest auth login --profile reporting ``` **Check A Remote Agent Connection** ```bash # Add MAILRITH_API_KEY through the runtime's secret settings first. npx @mailrith/cli@latest capabilities --json ``` ## Choose One Task And One Client Start with one outcome. Full Email Marketing Access is the default for a general-purpose agent. Choose Reporting for a read-only agent, Subscriber Management for a Subscriber sync, or Broadcasts for a dedicated Broadcast operator. Install the Mailrith plugin from the Plugins directory in ChatGPT or Codex, or connect the Mailrith Connector from Claude's Connectors Directory. Other supported clients can connect to the same hosted MCP endpoint through OAuth. Mailrith is provider-independent. OpenAI, Claude, Codex, n8n, Pipedream, and other clients use the same public API contract, workspace Permissions, and resource-verification behavior. AI Agent workflows are different from AI Writing. An agent connects from another client and can perform permitted workspace tasks. AI Writing creates copy inside a Mailrith editor and does not operate the workspace. - Reporting: workspace viewing plus the exact read tools the report needs. - Subscriber sync: Subscriber viewing and editing, with idempotency for repeatable jobs. - Broadcasts: create, read, edit, preflight, test, schedule, send, stop, delete, and monitor Broadcasts. - Sequences: create, read, edit, preflight, preview, test, activate, pause, delete, and manage Subscriber enrollment. ## Five-Minute Read-Only Quickstart This path uses OAuth, so the user connects Mailrith without copying a raw API key into an agent client. Mailrith defaults a general-purpose connection to Full Email Marketing Access. Choose Reporting for this deliberately read-only connection. If the client cannot complete OAuth, stop and use the documented server-side Bearer-token path. Never paste a workspace key into a prompt, chat message, exported workflow, or browser script. 1. Install `Mailrith` from `Plugins` in ChatGPT or Codex, or use `/plugins` in Codex CLI, then start a new ChatGPT chat or Codex session. In Claude, open `Customize` > `Connectors`, browse connectors, choose `Mailrith`, and select `Connect`. In another supported client, add a remote MCP server named `Mailrith` at `https://api.mailrith.com/mcp`. 2. Choose OAuth or select the client's `Connect` action. Sign in to Mailrith when the browser opens. 3. Choose the workspace, choose `Reporting` as the Work Profile, review the permissions, then approve only if the connection name and return address are expected. 4. Limit the client to `discovery_get_capabilities`, `workspace_get`, `subscribers_list`, and `subscribers_get`. 5. Ask: `Check the Mailrith connection, then list at most 10 recent Subscribers. Do not write or send anything.` 6. Confirm that the response identifies the selected workspace, returns no more than 10 Subscribers, and does not call a write or send tool. > The quickstart is complete only when capability discovery succeeds, the response identifies the selected workspace, the Subscriber result is bounded, and the client has no write or send tool enabled or called. The fixed Mailrith catalog can still list those tools for review. ## Broadcasts Quickstart The Broadcasts Work Profile covers the complete Broadcast lifecycle. If this workflow should prepare a draft without sending, limit the client to the draft, read, and preflight tools. 1. Create or update a dedicated OAuth connection with the `Broadcasts` Work Profile. 2. Allow `discovery_get_capabilities`, `sender_identities_list`, `segments_list`, `tags_list`, `email_templates_list`, `broadcasts_create`, `broadcasts_get`, `broadcasts_update`, and `broadcasts_preflight`. Do not allow `broadcasts_schedule` or `broadcasts_send`. 3. Ask the agent to create a Broadcast draft with a clear subject, preview text, structured `body_document`, sender, and selected Subscribers. 4. Ask the agent to use `broadcasts_get` and summarize the exact fields Mailrith stored. 5. Open `Campaigns`, click `Broadcasts`, open the draft, and review copy, links, merge fields, sender details, and selected Subscribers. 6. Run preflight, fix blocking issues, and leave the Broadcast as a draft when the requested task does not include sending. > A Broadcast write permission covers every Broadcast write operation. Tool limits narrow what the client exposes; the selected Work Profile remains the authorization boundary. ## Live-Send Quickstart A live send uses the same Broadcast delivery path as the Mailrith app. The connection must have `Manage Broadcasts`, and the Broadcast must pass the normal preflight and provider-readiness checks. Mailrith runs the send directly after resource authorization. Use a dedicated Broadcasts connection and expose the send tool only in workflows that should send. 1. Confirm the Broadcast is complete, the selected Subscribers are correct, and preflight has no blocking issues. 2. Create or reconnect a dedicated credential with the `Broadcasts` Work Profile. 3. Run `discovery_get_capabilities` and confirm that the connection has `broadcasts:write` and `live_actions:write`. 4. Allow `broadcasts_preflight`, `broadcasts_send`, and `broadcasts_get_send_progress`, then ask the agent to preflight and send the final Broadcast ID with a stable idempotency key. 5. Use `broadcasts_get_send_progress` and confirm the final delivery state before ending the workflow. 6. If the outcome is uncertain, inspect Broadcast progress and the saved Broadcast before retrying. ## Sequences And Operations Quickstart The Sequences Work Profile covers the complete Sequence lifecycle. Limit the tools exposed by the client when a workflow should prepare a paused Sequence without activating it. 1. In Mailrith, click `Settings` in the left sidebar, then click the `API Keys` tab. 2. Click `Generate API Key`, choose the workspace, enter a name, and select the `Sequences` Work Profile. 3. For a preparation-only workflow, expose `sequences_list`, `sequences_create`, `sequences_get`, `sequences_update`, `sequences_preflight`, and `sequences_preview_journey`. Omit `sequences_send_test`, `sequences_update_status`, and Subscriber enrollment tools. 4. Before activation, run `sequences_preflight` and inspect the side-effect-free `sequences_preview_journey` result. Use `sequences_send_test` only when the requested task includes sending selected saved emails to one address you control. 5. Run `sequences_update_status`, `subscribers_add_to_sequence`, or `subscribers_remove_from_sequence` only when the requested task includes that live change. 6. Open `Campaigns` → `Sequences` and confirm the saved status, steps, and Subscriber count. > Sequence test messages are limited to five saved emails and one explicit address. Sequences can also activate delivery to enrolled Subscribers, so grant it only to a connection that needs live Sequence control. ## Test Workspace Tutorial This is not a sandbox. Every saved change is real, and any permitted send or activation action can reach external systems or email addresses. Use a dedicated workspace with no real Subscribers before testing a new write workflow. Add one test-only email delivery connection so Mailrith applies the same creation rules everywhere, and expose only the tools needed for the test. 1. Create a workspace used only for agent testing. 2. Do not add real Subscribers. Connect a test email delivery provider and keep send and activation tools out of the agent client unless the test specifically covers them. 3. Connect the agent only to this workspace and run the read-only quickstart. 4. Create drafts for every supported resource the workflow needs. 5. Open each saved resource and confirm that its fields match the requested changes. 6. Delete the test resources when the review is complete. > Use the request ID from the response when asking support to investigate a failed or uncertain request. ## Related Guides - [Agents](https://mailrith.com/developers/agents.md): Mailrith supports OAuth directory connections for ChatGPT, Codex, and Claude, plus a compact discovery stack with llms files, API metadata, OpenAPI, authenticated capabilities, SDKs, and MCP entry points. - [AI Agent Architecture And Security](https://mailrith.com/developers/agent-security.md): 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. - [MCP Server](https://mailrith.com/developers/mcp.md): The Mailrith Connector is available in Claude, and the same remote MCP server supports OAuth or protected server-side credentials for OpenAI, n8n, Pipedream, and other clients.