com.mailrithPublished by mailrith.comOfficial publisherv2.0.1Updated Nov 4, 2026
Manage Subscribers, Broadcasts, Sequences, Automations, and reporting in Mailrith.
Official Mailrith MCP server that lets an assistant manage email marketing: subscribers, tags, segments, broadcasts, sequences and analytics.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/com.mailrith%2Fmailrith/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"mcpServers": {
"mailrith-email-marketing": {
"type": "http",
"url": "https://api.mailrith.com/mcp"
}
}
}Official MCP server for Mailrith.
The server uses the stable @modelcontextprotocol/sdk package for hosted and
stdio transports while preserving Mailrith's generated operation schemas.
Use the remote MCP endpoint at https://api.mailrith.com/mcp for hosted agent
integrations, or run the local server from this repo for stdio or self-hosted HTTP use.
Claude Desktop and other user-connected remote MCP clients authenticate through
Mailrith OAuth. Code-first clients that can safely store credentials may send a
workspace API key or OAuth access token as Authorization: Bearer <credential>.
The registry metadata in server.json identifies the server as
com.mailrith/mailrith. Clients can use the canonical Streamable HTTP endpoint
at https://api.mailrith.com/mcp, which authenticates through OAuth, or install
the local stdio package from npm. Local installs require a workspace API key in
MAILRITH_API_KEY.
The hosted server requests Full Email Marketing Access by default for a
general-purpose agent. It covers every public email-marketing operation in the
selected workspace, but not billing, team, account-security,
credential-reading, or internal administration. The
discovery_get_capabilities connection check requests the complete public
permission catalog so Mailrith can show every Work Profile and default to Full
Email Marketing Access. The user can choose Reporting, another focused Work
Profile, or custom permissions instead. OAuth stores only the permissions the
user approves, and every tool checks those permissions again when it runs.
Local stdio reads MAILRITH_API_KEY from the client secret environment. The
server rejects credentials passed as command arguments so they do not appear in
process listings or shell history. Local stdio stops with a clear setup error
when the environment variable is missing because it has no browser-based OAuth
flow.
Self-hosted HTTP does not read a process-wide API key. Each client must send its
own workspace API key or OAuth access token in the Authorization header. The
built-in HTTP listener accepts only 127.0.0.1 or localhost; put a TLS reverse
proxy in front of it when another machine needs access.
The default submitted profile exposes a fixed reviewed catalog of focused
tools such as:
subscribers_listbroadcasts_createbroadcasts_preflightbroadcasts_schedulebroadcasts_sendsequences_update_statusautomations_update_statusEvery submitted tool has a human-readable top-level title and
annotations.title, a narrow description, exact input and output schemas,
explicit safety annotations, and machine-readable operation permissions.
Request-body inputs expose their JSON type directly as well as their exact
referenced schema so connector review tools can validate them without expanding
$ref values first. Tools other than the connection check advertise their
exact OAuth permissions. The connection check advertises the complete
permission catalog so OAuth can offer every Work Profile; its result still
reports the exact permissions granted to the connection. The catalog stays the
same for every user so clients can review and select tools reliably. Workspace
role, plan, product readiness, and granted permissions are enforced when a tool
runs.
Anonymous clients may initialize and list this static catalog so ChatGPT and
other hosts can start OAuth linking. Anonymous tool calls never reach the
Mailrith product API and return HTTP 401 with a standards-based
WWW-Authenticate challenge instead. Authenticated calls that need more
permissions return HTTP 403 with the complete replacement permission set.
Single-tool responses also include MCP's tool-level OAuth challenge metadata
for clients that use it when linking or reconnecting an account.
Each anonymous HTTP request accepts one JSON-RPC message. Authenticated
requests may batch up to 25 messages. These limits keep discovery and tool
responses predictable for every connected workspace.
Automation reads never return saved webhook bearer tokens or custom header values. They return only whether each value is configured. If a client reads an Automation and sends the redacted definition back during an update, Mailrith preserves the existing values unless the client explicitly replaces or removes them. Changing the webhook destination requires new credential values so an old secret cannot be carried to another service.
The package also preserves two explicit compatibility profiles:
compact exposes the earlier seven discovery and routing tools.custom exposes generated focused tools with caller-selected Work Profile,
permission, and read-only filters.Use these profiles only for local or purpose-built clients. Public ChatGPT,
Codex, Claude, and Cursor packages use the fixed submitted profile at the
single /mcp endpoint.
Modified public versions must use distinct package, registry, plugin, and service names and clearly say that they are unofficial. See the Mailrith Trademark And Unofficial Fork Policy.
Source: packages/mcp-server/README.md at commit f54599a
Get authenticated API capabilities
Returns the current workspace context, discovery URLs, shared request conventions, supported webhook events, and public resource operations available to the authenticated bearer credential. Permission: none. API reference: https://mailrith.com/developers/api-reference.
Takes no parameters.
Get the current workspace
Returns the authenticated workspace profile and mailing context used by broadcasts, sequences, automations, forms, and magic links. Permission: workspace:read. API reference: https://mailrith.com/developers/api-reference.
Takes no parameters.
List sender identities
Returns a bounded page of enabled sender names, addresses, and provider types that can be selected for Broadcasts and Sequences. Provider credentials and configuration are never returned. Permission: workspace:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitstarting_afterGet a sender identity
Returns one enabled sender name, address, and provider type by stable identifier. Provider credentials and configuration are never returned. Permission: workspace:read. API reference: https://mailrith.com/developers/api-reference.
sender_identity_idrequiredCreate or reuse an analytics report
Runs from compact rollups. Ranges through 31 days complete inline; longer ranges are queued. Results expire after 24 hours and never exceed 100 rows. Effect: workspace-change. Retry with the same idempotency_key. Permission: analytics:read. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyGet an analytics report
Returns one unexpired bounded analytics report by identifier. Permission: analytics:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitreport_idrequiredstarting_afterList subscribers
Returns subscribers in the authenticated workspace, sorted from newest to oldest. Permission: subscribers:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
emaillimitsearchstatustag_idtag_idscold_onlysequence_idsequence_idstag_operatorstarting_aftersequence_operatorGet a subscriber
Returns one Subscriber by its stable identifier from the authenticated workspace. Permission: subscribers:read. API reference: https://mailrith.com/developers/api-reference.
subscriber_idrequiredCreate 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. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyUpdate 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. Effect: subscriber-change. Retry after reading the current resource state. Permission: subscribers:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredsubscriber_idrequiredChange Subscriber sending eligibility
Changes the delivery status for one Subscriber without changing profile, targeting, or Sequence enrollment fields. Making a Subscriber Active requires consent_evidence; its collected_at value must include the correct UTC offset and must not be later than Mailrith's server time. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredsubscriber_idrequiredAdd a Tag to a Subscriber
Adds the selected Tag to a Subscriber. If the Subscriber already has the Tag, the API returns the Subscriber unchanged. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
tag_idrequiredsubscriber_idrequiredRemove 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. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
tag_idrequiredsubscriber_idrequiredAdd 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. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
sequence_idrequiredsubscriber_idrequiredRemove 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. Effect: subscriber-change. Retry after reading the current resource state. Permissions: live_actions:write, subscribers:write. API reference: https://mailrith.com/developers/api-reference.
sequence_idrequiredsubscriber_idrequiredList tags
Returns tags in the authenticated workspace. Permission: tags:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterGet a tag
Returns one Tag from the authenticated workspace. Permission: tags:read. API reference: https://mailrith.com/developers/api-reference.
tag_idrequiredCreate 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. Effect: workspace-change. Retry with the same idempotency_key. Permission: tags:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyList custom fields
Returns a bounded page of custom fields in the authenticated workspace, including each field's exact ready-to-use email personalization token. Permission: custom_fields:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterGet a custom field
Returns one custom field from the authenticated workspace, including its exact ready-to-use email personalization token. Permission: custom_fields:read. API reference: https://mailrith.com/developers/api-reference.
custom_field_idrequiredList segments
Returns saved segments from the authenticated workspace. Permission: segments:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterGet a segment
Returns one saved segment from the authenticated workspace. Permission: segments:read. API reference: https://mailrith.com/developers/api-reference.
segment_idrequiredPreview 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. Permission: segments:read. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredList broadcasts
Returns broadcast drafts, scheduled sends, active sends, and completed sends. Permission: broadcasts:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterCreate a broadcast
Creates a broadcast draft in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyGet a broadcast
Returns a broadcast draft, scheduled send, active send, or completed send. Permission: broadcasts:read. API reference: https://mailrith.com/developers/api-reference.
broadcast_idrequiredUpdate a broadcast
Updates an existing Broadcast draft. Scheduled, running, completed, and failed Broadcasts cannot be changed here. Before changing a scheduled Broadcast, read it by ID and retain its scheduled_at in the current task only. If the saved time is no longer safely in the future, ask the user for a new time before unscheduling. Otherwise unschedule it, apply the update, reschedule it for the same time, and verify both status and scheduled_at. If the update fails after unscheduling, restore the unchanged Broadcast to the same future time when possible. If the schedule cannot be restored, leave it as a Draft and immediately report that it will not send; never choose a replacement time without the user. Effect: workspace-change. Retry after reading the current resource state. Permission: broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredbroadcast_idrequiredInspect broadcast readiness
Optionally checks the current Subscriber estimate, provider capacity, sender setup, event tracking, and blocking issues. This diagnostic is not required before starting a durable send. Permission: broadcasts:read. API reference: https://mailrith.com/developers/api-reference.
broadcast_idrequiredSend a broadcast test email
Sends a test message from an existing Broadcast that has a sender. Provide a saved Subscriber ID for personalization; use subscribers_list to find one when needed. The recipient may be any test inbox and does not have to match the saved Subscriber. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredbroadcast_idrequiredidempotency_keySchedule or reschedule a broadcast
Schedules a draft for future delivery, or changes the delivery time of an existing scheduled Broadcast. This uses Mailrith's durable scheduled-send path and does not start delivery immediately. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredbroadcast_idrequiredUnschedule a broadcast
Returns a scheduled Broadcast to draft state before delivery starts. Effect: workspace-change. Retry after reading the current resource state. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
broadcast_idrequiredSend a broadcast now
Immediately creates durable preparation for a broadcast draft or scheduled send. Mailrith calculates the exact Subscriber total and checks provider readiness in the background before delivery. 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. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
bodybroadcast_idrequiredidempotency_keyCancel 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. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, broadcasts:write. API reference: https://mailrith.com/developers/api-reference.
broadcast_idrequiredidempotency_keyGet 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. Permission: broadcasts:read. Polling: wait at least 2 seconds, use exponential backoff up to 30 seconds, stop at a terminal state, and stop after 15 minutes. API reference: https://mailrith.com/developers/api-reference.
broadcast_idrequiredList sequences
Returns sequences in the authenticated workspace. Permission: sequences:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterCreate a sequence
Creates a sequence in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: sequences:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyGet a sequence
Returns one sequence from the authenticated workspace. Permission: sequences:read. API reference: https://mailrith.com/developers/api-reference.
sequence_idrequiredUpdate a sequence
Updates an existing paused Sequence. Before changing a running Sequence, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Sequence, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate a Sequence that was not already running. Effect: workspace-change. Retry after reading the current resource state. Permission: sequences:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredsequence_idrequiredCheck sequence readiness
Checks the saved Sequence, its published emails, and its sender without changing data or sending email. Permission: sequences:read. API reference: https://mailrith.com/developers/api-reference.
sequence_idrequiredPreview a sequence journey
Returns the bounded saved email timeline and shows which messages a selected Subscriber is eligible to receive, without enrolling the Subscriber or sending email. Permissions: subscribers:read, sequences:read. API reference: https://mailrith.com/developers/api-reference.
sequence_idrequiredsubscriber_idrequiredSend sequence test messages
Sends up to five selected saved Sequence emails to one explicit test address. This does not enroll a Subscriber, start the Sequence, or write delivery activity. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, sequences:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredsequence_idrequiredidempotency_keyActivate or pause a sequence
Starts or pauses one Sequence without changing its content or delivery settings. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, sequences:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredsequence_idrequiredList automations
Returns automations in the authenticated workspace. Permission: automations:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterCreate an automation
Creates an automation in the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: automations:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyGet an automation
Returns one automation from the authenticated workspace. Permission: automations:read. API reference: https://mailrith.com/developers/api-reference.
automation_idrequiredUpdate an automation
Updates an existing draft or paused Automation. Before changing a running Automation, read it by ID, retain its status in the current task only, pause it, apply the update, and use bounded direct item reads until is_updating is false. Run preflight, return it to running only if it was running before and preflight passes, and verify the final status. If the update fails before changing the Automation, restore its prior running status when preflight passes. If readiness or the prior status cannot be restored, leave it paused and immediately report the failure; never activate an Automation that was not already running. Effect: workspace-change. Retry after reading the current resource state. Permission: automations:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredautomation_idrequiredCheck automation readiness
Checks the saved Automation definition and email delivery prerequisite without running any action. Permission: automations:read. API reference: https://mailrith.com/developers/api-reference.
automation_idrequiredPreview an automation journey
Shows the bounded path a selected Subscriber would take through the current saved conditions without running actions or writing history. Permissions: subscribers:read, automations:read. API reference: https://mailrith.com/developers/api-reference.
automation_idrequiredsubscriber_idrequiredSend automation test messages
Sends up to five selected saved Automation email steps to one explicit test address. This does not start the Automation or run other actions. Effect: external-email. Retry with the same idempotency_key. Permissions: live_actions:write, subscribers:read, automations:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredautomation_idrequiredidempotency_keyChange an automation status
Starts, pauses, or returns one Automation to draft without changing its definition. Effect: external-email. Retry after reading the current resource state. Permissions: live_actions:write, automations:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredautomation_idrequiredList email templates
Returns reusable email templates linked to the authenticated workspace. Permission: email_templates:read. Pagination: use bounded pages and returned cursors. API reference: https://mailrith.com/developers/api-reference.
limitsearchstarting_afterCreate an email template
Creates a reusable email template scoped to the authenticated workspace. Effect: workspace-change. Retry with the same idempotency_key. Permission: email_templates:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredidempotency_keyGet an email template
Returns a reusable email template linked to the authenticated workspace. Permission: email_templates:read. API reference: https://mailrith.com/developers/api-reference.
template_idrequiredPreview an email template for a Subscriber
Renders one template using a saved Subscriber's name, email, and custom fields without sending or saving anything. Permissions: subscribers:read, email_templates:read. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredtemplate_idrequiredUpdate an email template
Updates the content or enabled state of an existing email template. Effect: workspace-change. Retry after reading the current resource state. Permission: email_templates:write. API reference: https://mailrith.com/developers/api-reference.
bodyrequiredtemplate_idrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
MAILRITH_API_KEY="<secret>" pnpm --filter @mailrith/mcp-server exec tsx src/cli.ts --transport stdio