Mailrith
Start

Browse developer docs

Switch between integration guides, resources, and platform rules.

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 once a workspace key is available.

4 min read

Use a deterministic discovery flow

Agents should start with Mailrith's unauthenticated discovery surfaces, then switch to authenticated discovery once a workspace API key is available.

The recommended order is: read llms.txt, inspect GET /v1, load GET /v1/openapi.json, then call GET /v1/capabilities with the target workspace key before choosing whether to use the REST API, an official SDK, or the MCP server.

  • Read /llms.txt for the compact agent-oriented index.
  • Read /llms-full.txt for the longer version with workflow guidance and current public-surface boundaries.
  • Call /v1/capabilities after authentication to confirm the exact resource operations currently available to the key.

Machine-readable entry points

Mailrith publishes both human and machine entry points so agent runtimes can choose the level of fidelity they need.

Unauthenticated discovery 
curl https://mailrith.com/llms.txt
curl https://mailrith.com/llms-full.txt
curl https://api.mailrith.com/v1
curl https://api.mailrith.com/v1/openapi.json
Authenticated capability discovery 
curl https://api.mailrith.com/v1/capabilities \
  -H "Authorization: Bearer mrk_example_secret_key"

Current agent-safe tasks

The current public v1 surface covers audience sync, the Mailrith campaign and automation control plane, machine-safe webhook subscriptions, and async import or export orchestration.

  • Inspect the authenticated workspace, subscribers, tags, custom fields, segments, and forms.
  • Create and manage email templates, sequences, automations, magic links, broadcasts, and webhook subscriptions.
  • Queue subscriber import and export jobs, then react to updates through signed developer webhooks instead of polling.
GET /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
GET /v1/subscribers

List subscribers

Returns subscribers in the authenticated workspace, ordered from newest to oldest.

View schema
POST /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 existing subscriber is updated instead.

View schema
GET /v1/tags

List tags

Returns tags in the authenticated workspace.

View schema
POST /v1/tags

Create a tag

Creates a new tag in the authenticated workspace.

View schema
GET /v1/custom-fields

List custom fields

Returns custom fields available to the authenticated workspace.

View schema
GET /v1/email-templates

List email templates

Returns reusable email templates linked to the authenticated workspace.

View schema
POST /v1/email-templates

Create an email template

Creates a reusable email template scoped to the authenticated workspace.

View schema
GET /v1/email-templates/{template_id}

Get an email template

Returns a reusable email template linked to the authenticated workspace.

View schema
PUT /v1/email-templates/{template_id}

Update an email template

Updates the content or enabled state of an existing email template.

View schema
DELETE /v1/email-templates/{template_id}

Delete an email template

Deletes an existing email template linked to the authenticated workspace.

View schema
GET /v1/forms

List forms

Returns forms in the authenticated workspace.

View schema
POST /v1/forms

Create a form

Creates a form in the authenticated workspace.

View schema
GET /v1/forms/{form_id}

Get a form

Returns a form in the authenticated workspace.

View schema
PUT /v1/forms/{form_id}

Update a form

Updates an existing form in place.

View schema
DELETE /v1/forms/{form_id}

Delete a form

Deletes a form from the authenticated workspace.

View schema
GET /v1/sequences

List sequences

Returns sequences available in the authenticated workspace.

View schema
POST /v1/sequences

Create a sequence

Creates a sequence in the authenticated workspace.

View schema
GET /v1/sequences/{sequence_id}

Get a sequence

Returns a sequence in the authenticated workspace.

View schema
PUT /v1/sequences/{sequence_id}

Update a sequence

Updates an existing sequence in place.

View schema
DELETE /v1/sequences/{sequence_id}

Delete a sequence

Deletes an existing sequence from the authenticated workspace.

View schema
GET /v1/automations

List automations

Returns automations available in the authenticated workspace.

View schema
POST /v1/automations

Create an automation

Creates an automation in the authenticated workspace.

View schema
GET /v1/automations/{automation_id}

Get an automation

Returns an automation in the authenticated workspace.

View schema
PUT /v1/automations/{automation_id}

Update an automation

Updates an existing automation in place.

View schema
DELETE /v1/automations/{automation_id}

Delete an automation

Deletes an automation from the authenticated workspace.

View schema
GET /v1/magic-links

List magic links

Returns magic links available in the authenticated workspace.

View schema
POST /v1/magic-links

Create a magic link

Creates a magic link in the authenticated workspace.

View schema
GET /v1/magic-links/{magic_link_id}

Get a magic link

Returns a magic link in the authenticated workspace.

View schema
PUT /v1/magic-links/{magic_link_id}

Update a magic link

Updates an existing magic link in place.

View schema
DELETE /v1/magic-links/{magic_link_id}

Delete a magic link

Deletes a magic link from the authenticated workspace.

View schema
GET /v1/broadcasts

List broadcasts

Returns broadcast drafts, scheduled sends, active sends, and completed sends.

View schema
POST /v1/broadcasts

Create a broadcast

Creates a broadcast draft or scheduled broadcast in the authenticated workspace.

View schema
GET /v1/broadcasts/{broadcast_id}

Get a broadcast

Returns a broadcast draft, scheduled send, active send, or completed send.

View schema
PUT /v1/broadcasts/{broadcast_id}

Update a broadcast

Updates a broadcast draft or scheduled send in place.

View schema
DELETE /v1/broadcasts/{broadcast_id}

Delete a broadcast

Deletes an existing broadcast from the authenticated workspace.

View schema
POST /v1/broadcasts/{broadcast_id}/send

Send a broadcast now

Launches immediate delivery for a broadcast draft or scheduled send.

View schema
POST /v1/broadcasts/{broadcast_id}/test

Send a broadcast test email

Sends a test message for an existing broadcast to a single recipient.

View schema
GET /v1/segments

List segments

Returns saved segments in the authenticated workspace.

View schema
POST /v1/segments/preview

Preview a segment definition

Returns subscriber counts for an unsaved audience definition.

View schema
POST /v1/jobs/subscriber-exports

Create a subscriber export job

Queues an asynchronous subscriber export for the authenticated workspace.

View schema
GET /v1/jobs/subscriber-exports/{job_id}

Get a subscriber export job

Returns the current state of a previously created export job.

View schema
POST /v1/jobs/subscriber-imports

Create a subscriber import job

Queues an asynchronous subscriber import from CSV text.

View schema
GET /v1/jobs/subscriber-imports/{job_id}

Get a subscriber import job

Returns the current state of a previously created import job.

View schema

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.

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

Related guides

4 min read
SDKs

Use the official TypeScript and Python SDKs generated from Mailrith's public contract.
5 min read
MCP Server

Connect Mailrith to agent runtimes through the official remote MCP server and streamable HTTP transport.
6 min read
API Reference

Browse the generated endpoint reference and download the OpenAPI contract.
Previous
Testing the API
Next
SDKs

On this page

Jump to the section you need.