AI Agent Quickstarts

Follow task-based paths for a five-minute read, complete Broadcast and Sequence workflows, and dedicated test-workspace testing without giving an agent broad workspace control.

12 min read

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.

Mailrith is provider-independent. OpenAI, Claude, Codex, n8n, Pipedream, and other clients use the same hosted MCP endpoint, 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.

Open the agent client's MCP or connector settings and add a remote server named Mailrith.
Enter https://api.mailrith.com/mcp as the Streamable HTTP server URL.
Choose OAuth or click the client's Connect action. Sign in to Mailrith when the browser opens.
Choose the workspace, choose Reporting as the Work Profile, review the permissions, then approve only if the connection name and return address are expected.
Limit the client to discovery_get_capabilities, workspace_get, subscribers_list, and subscribers_get.
Ask: Check the Mailrith connection, then list at most 10 recent Subscribers. Do not write or send anything.
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.

Create or update a dedicated OAuth connection with the Broadcasts Work Profile.
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.
Ask the agent to create a Broadcast draft with a clear subject, preview text, structured body_document, sender, and selected Subscribers.
Ask the agent to use broadcasts_get and summarize the exact fields Mailrith stored.
Open Campaigns, click Broadcasts, open the draft, and review copy, links, merge fields, sender details, and selected Subscribers.
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.

Confirm the Broadcast is complete, the selected Subscribers are correct, and preflight has no blocking issues.
Create or reconnect a dedicated credential with the Broadcasts Work Profile.
Run discovery_get_capabilities and confirm that the connection has broadcasts:write and live_actions:write.
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.
Use broadcasts_get_send_progress and confirm the final delivery state before ending the workflow.
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.

In Mailrith, click Settings in the left sidebar, then click the API Keys tab.
Click Generate API Key, choose the workspace, enter a name, and select the Sequences Work Profile.
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.
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.
Run sequences_update_status, subscribers_add_to_sequence, or subscribers_remove_from_sequence only when the requested task includes that live change.
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

Use a dedicated workspace with no real Subscribers before testing a new write workflow. Add one active email delivery connection so Mailrith applies the same creation rules everywhere, and expose only the tools needed for the test.

Create a workspace used only for agent testing.
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.
Connect the agent only to this workspace and run the read-only quickstart.
Create drafts for every supported resource the workflow needs.
Open each saved resource and confirm that its fields match the requested changes.
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.

Need Help Shipping an Integration?

Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.

Contact Mailrith

Agents

AI Agent Architecture And Security