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.
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.
- Read
https://mailrith.com/llms.txtfor the compact integration index. - Read
https://mailrith.com/llms-full.txtwhen the agent needs detailed workflow guidance. - Read
https://mailrith.com/.well-known/api-catalogwhen the runtime supports well-known API discovery. - Call
GET /v1to confirm the API version metadata. - Load
GET /v1/openapi.jsonso the agent has exact request and response schemas. - Create or provide a workspace API key only after the agent knows what action it needs to perform.
- Call
GET /v1/capabilitieswith that key to confirm workspace-specific access. - Choose REST, SDKs, or MCP Server based on the runtime and risk level.
- Read
/llms.txtfor the compact agent-oriented index. - Read
/llms-full.txtwhen 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.jsonwhen an agent platform discovers integrations from the marketing domain. - Call
/v1/capabilitiesafter 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.
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.jsoncurl 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.
/v1/workspace Get the current workspace
Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links.
View Schema /v1/subscribers List subscribers
Returns subscribers in the authenticated workspace, sorted from newest to oldest.
View Schema /v1/subscribers Create or upsert a subscriber
Creates a new subscriber when the email does not exist in the workspace. If the email already exists, the API updates the existing subscriber unless create_only is true.
View Schema /v1/subscribers/{subscriber_id} Update a subscriber
Updates profile fields, status, custom fields, tags, or sequence assignments for one subscriber. Fields omitted from the request stay unchanged. Blank optional custom field values also leave saved values unchanged, and filled-in invalid values are rejected.
View Schema /v1/subscribers/{subscriber_id}/sequences/{sequence_id} Add a subscriber to a sequence
Adds the selected subscriber to the selected sequence. If the subscriber is already in the sequence, the API returns the subscriber unchanged.
View Schema /v1/subscribers/{subscriber_id}/sequences/{sequence_id} Remove a subscriber from a sequence
Removes the selected subscriber from the selected sequence. If the subscriber is not in the sequence, the API returns the subscriber unchanged.
View Schema /v1/subscribers/{subscriber_id}/tags/{tag_id} Remove a tag from a subscriber
Removes the selected tag from a subscriber. If the subscriber does not have the tag, the API returns the subscriber unchanged.
View Schema /v1/tags List tags
Returns tags in the authenticated workspace.
View Schema /v1/tags Create a tag
Creates a new tag in the authenticated workspace. The GDPR consent tag names can be created and applied like other tags when you need to apply consent collected outside Mailrith. Tag-level double opt-in fields are no longer accepted; configure double opt-in on forms and landing pages instead.
View Schema /v1/custom-fields List custom fields
Returns custom fields in the authenticated workspace.
View Schema /v1/custom-fields Create a custom field
Creates a workspace-scoped custom-field definition.
View Schema /v1/custom-fields/{custom_field_id} Get a custom field
Returns one custom field from the authenticated workspace.
View Schema /v1/custom-fields/{custom_field_id} Update a custom field
Updates a custom-field definition for the authenticated workspace.
View Schema /v1/custom-fields/{custom_field_id} Delete a custom field
Deletes a custom-field definition from the authenticated workspace.
View Schema /v1/email-templates List email templates
Returns reusable email templates linked to the authenticated workspace.
View Schema /v1/email-templates Create an email template
Creates a reusable email template scoped to the authenticated workspace.
View Schema /v1/email-templates/{template_id} Get an email template
Returns a reusable email template linked to the authenticated workspace.
View Schema /v1/email-templates/{template_id} Update an email template
Updates the content or enabled state of an existing email template.
View Schema /v1/email-templates/{template_id} Delete an email template
Deletes an existing email template linked to the authenticated workspace.
View Schema /v1/forms List forms
Returns forms from the authenticated workspace.
View Schema /v1/forms Create a form
Creates a form in the authenticated workspace.
View Schema /v1/forms/{form_id} Get a form
Returns a form from the authenticated workspace.
View Schema /v1/forms/{form_id} Update a form
Updates an existing form without creating a new form.
View Schema /v1/forms/{form_id} Delete a form
Deletes a form from the authenticated workspace.
View Schema /v1/forms/{form_id}/submissions List form submissions
Returns recent real submissions for one form, including the subscriber who submitted the form. Requires both `forms:read` and `subscribers:read`.
View Schema /v1/sequences List sequences
Returns sequences in the authenticated workspace.
View Schema /v1/sequences Create a sequence
Creates a sequence in the authenticated workspace.
View Schema /v1/sequences/{sequence_id} Get a sequence
Returns one sequence from the authenticated workspace.
View Schema /v1/sequences/{sequence_id} Update a sequence
Updates an existing sequence.
View Schema /v1/sequences/{sequence_id} Delete a sequence
Deletes an existing sequence from the authenticated workspace.
View Schema /v1/automations List automations
Returns automations in the authenticated workspace.
View Schema /v1/automations Create an automation
Creates an automation in the authenticated workspace.
View Schema /v1/automations/{automation_id} Get an automation
Returns one automation from the authenticated workspace.
View Schema /v1/automations/{automation_id} Update an automation
Updates an existing automation.
View Schema /v1/automations/{automation_id} Delete an automation
Deletes an automation from the authenticated workspace.
View Schema /v1/magic-links List magic links
Returns magic links in the authenticated workspace.
View Schema /v1/magic-links Create a magic link
Creates a magic link in the authenticated workspace.
View Schema /v1/magic-links/{magic_link_id} Get a magic link
Returns one magic link from the authenticated workspace.
View Schema /v1/magic-links/{magic_link_id} Update a magic link
Updates an existing magic link.
View Schema /v1/magic-links/{magic_link_id} Delete a magic link
Deletes a magic link from the authenticated workspace.
View Schema /v1/broadcasts List broadcasts
Returns broadcast drafts, scheduled sends, active sends, and completed sends.
View Schema /v1/broadcasts Create a broadcast
Creates a broadcast draft or scheduled broadcast in the authenticated workspace.
View Schema /v1/broadcasts/{broadcast_id} Get a broadcast
Returns a broadcast draft, scheduled send, active send, or completed send.
View Schema /v1/broadcasts/{broadcast_id} Update a broadcast
Updates a broadcast draft or scheduled send in place.
View Schema /v1/broadcasts/{broadcast_id} Delete a broadcast
Deletes a draft, scheduled, or failed broadcast from the authenticated workspace. Broadcasts cannot be deleted after they start sending.
View Schema /v1/broadcasts/{broadcast_id}/cancel Cancel a broadcast send
Requests cancellation for delivery work that has not reached the provider. Provider-accepted emails cannot be recalled. Repeat the same request with the same idempotency key when the response is lost.
View Schema /v1/broadcasts/{broadcast_id}/delivery-errors List broadcast delivery errors
Returns a cursor-paginated page of permanent failures and unknown delivery results.
View Schema /v1/broadcasts/{broadcast_id}/preflight Check a broadcast before sending
Checks the current Subscriber estimate, provider capacity, sender setup, event tracking, and high-volume confirmation requirement.
View Schema /v1/broadcasts/{broadcast_id}/progress Get broadcast send progress
Returns bounded delivery progress, current rates, timing, outcome counts, and pause state. Poll until terminal is true; use 5 to 10 second intervals while progress changes and back off to 30 seconds when unchanged.
View Schema /v1/broadcasts/{broadcast_id}/send Send a broadcast now
Accepts asynchronous delivery for a broadcast draft or scheduled send. A 202 response means the durable send was accepted, not that provider delivery is complete. Reuse the same idempotency key if the response is lost.
View Schema /v1/broadcasts/{broadcast_id}/test Send a broadcast test email
Sends a test message from an existing broadcast to one recipient.
View Schema /v1/segments List segments
Returns saved segments from the authenticated workspace.
View Schema /v1/segments Create a segment
Creates a saved segment in the authenticated workspace.
View Schema /v1/segments/{segment_id} Get a segment
Returns one saved segment from the authenticated workspace.
View Schema /v1/segments/{segment_id} Update a segment
Updates a saved segment in the authenticated workspace.
View Schema /v1/segments/{segment_id} Delete a segment
Deletes a saved segment from the authenticated workspace.
View Schema /v1/segments/preview Preview a segment definition
Returns subscriber counts for an unsaved segment definition. Include `current_segment_id` when previewing edits to an existing segment so circular segment references are rejected before saving.
View Schema /v1/jobs/subscriber-exports Create a subscriber export job
Queues an asynchronous subscriber export for the authenticated workspace. Requires `jobs:write` and `subscribers:read` because the finished file contains subscriber data.
View Schema /v1/jobs/subscriber-exports/{job_id} Get a subscriber export job
Returns the current state of a previously created export job. Requires `jobs:read` and `subscribers:read` because completed jobs include a subscriber CSV download URL.
View Schema /v1/jobs/subscriber-imports Create a subscriber import job
Queues an asynchronous import job that creates or updates subscribers from CSV text.
View Schema /v1/jobs/subscriber-imports/{job_id} Get a subscriber import job
Returns the current state of a previously created import job.
View SchemaFor 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.
Need Help Shipping an Integration?
Reach the Mailrith team if you need help planning a sync, validating a webhook flow, or troubleshooting a request.