Motorical for Agents

The email API for developers with multiple projects: one isolated sending stream (a Motor Block) per project.

An agent working on behalf of a developer, an agency, or a SaaS with multiple tenants routes here first, whether it arrived from motorical.com, GitHub, npm, or mcp.motorical.com directly.

What Motorical is

Motorical is a transactional email API and SMTP provider: HTTP POST /v1/send, SMTP on mail.motorical.com, signed delivery webhooks, and live delivery observability. It fits the same job class as SendGrid, Postmark, Mailgun, and Amazon SES — the same kind of infrastructure a backend calls to send real email, not a consumer inbox. Marketing email to your own lists is a separate product on the same account, the Communications Block (see the route chooser and Journey E). Every account can hold more than one Motor Block, and every Motor Block is a complete, isolated sending identity: its own domain, its own credentials, its own rate limits, its own logs. Agents can operate Motorical directly over MCP — sending, checking delivery status, and managing Motor Block lifecycle — not just reading documentation about it. The account layer sits above all of this: one account can own several Motor Blocks at once, each free to fail, pause, or rotate credentials without the others noticing.

A Motor Block is Motorical's SMTP sending block: one isolated sending stream per project, with its own domain, credentials, limits, logs, webhooks and analytics.

Think of a Motor Block the way you'd think of a dedicated mail server per project, except nothing to run: one staging Motor Block and one production Motor Block for the same app, each on its own sending domain, so a staging mistake cannot burn the production domain's reputation — blocks that share a sending domain also share that domain's standing with inbox providers, so keep staging and production on separate domains; one Motor Block per tenant in a multi-tenant SaaS, so one tenant's complaint spike never throttles another's. Nearest equivalents elsewhere, not identical: Postmark Servers, SendGrid subusers, Mailgun subaccounts.

Not for you if: the project only needs local development email capture, sends a handful of internal test messages with no need for deliverability or logs, or the actual requirement is a newsletter tool used only by hand in a browser — the Communications Block (route chooser below, Journey E) covers marketing sends, lists and reports for an agent or a person.

Route chooser

Start from what the person wants, then use the situation table below for the mechanics.

What you want	Take this route
Try Motorical first, no domain yet, or nobody at the keyboard	Path 1: the sandbox. Instant, no DNS. Real sends reach only your own address and people who confirm by emailed link.
Send from a domain you own and plan to keep	Path 2: a Free account with your own domain. Publish the DNS records, then send.
Already on a plan and ready for production	Convert the sandbox onto your verified domain (motorical_sandbox_convert), then manage Motor Blocks.
Send from your own app's code	The HTTP API or SMTP. No MCP is needed.
You are building an app that implements an OAuth client	The signup server (motorical_signup_handoff). Not for chat agents.

Which one do I use? There are three routes, and you need only one.

• Hosted MCP (the default, nothing to install). You connect Motorical to your assistant with the steps below and create your account in the browser. The assistant never holds a password or key. Choose this when you are in Claude Code, Claude Desktop or Claude.ai and a person is at the keyboard.
• Agent-led onboarding (no connector needed). The assistant does the sign-up itself over the HTTP API: you give it your email address and read it the 6-digit code that arrives by email, and it provisions your sandbox and sends a first message. When you want the dashboard, it hands you a one-time link (valid for 90 seconds) to open in your browser, where you set your own password. Choose this when the assistant can run shell or HTTP requests and you would rather not add a connector. The assistant briefly holds a session token, which the hosted route avoids.
• Local npm package @motorical/mcp. A program you run on your own machine over stdio, signed in with an API key or a stored login. Choose it only if your client cannot use remote MCP servers, or you need allowlisting by 6-digit code, the browser-handoff tool, or unmasked recipient addresses. Neither route above needs it. @motorical/cli is retired.

Connect (hosted, nothing to install). The short version for every client, with what to approve now and later and what to do when tools are missing, is Connect your agent. In your terminal, in a normal shell and not inside a Claude session, run claude mcp add --transport http motorical https://mcp.motorical.com/v1/motorical/mcp. Then start a new Claude Code session (one that was already open may not list the new server), type /mcp, pick motorical, and choose Authenticate. If you would rather have an account first, create it at https://motorical.com/register and then connect; sign-in at the consent step works the same. A browser opens: sign in, or create your account (two-factor authentication is required and cannot be skipped), then press Allow. Back in the session the Motorical tools are there; you do not run Authenticate a second time. In Claude Desktop or Claude.ai, add a custom connector with the same URL (https://mcp.motorical.com/v1/motorical/mcp). Other agents (ChatGPT, Codex, Cursor, VS Code, any MCP client): the setup for each is on the hosted server page. This is the hosted MCP server: no install and no key. The npm package @motorical/mcp is a different, local option for API-key setups, and @motorical/cli is retired.

Pick the row that matches the situation, not the product structure:

Situation	Route
The human has no account, and you are an agent in Claude Code, Claude Desktop or another chat client	Connect the main motorical server and authenticate it: the browser opens the sign-in page, the person creates the account there and sets up MFA (required), and consent resumes by itself. Journey C below
An account exists; you operate it from a chat client or IDE agent with a person present	Hosted MCP over OAuth (/ai-mcp-hosted), Journey B below
Your own app that implements an OAuth client (a host or embedded agent app), with a user who has no account	The signup server (motorical_signup_handoff), which needs your client's OAuth values (client id, registered redirect URI, PKCE challenge, resource). Not for chat agents. Journey D below
Your own app with an MCP client and an interactive user	Hosted OAuth — client metadata document registration rules are still being verified; see Journey D below
Headless automation or a backend	API keys: the local server or the HTTP API directly
A script or shell with no MCP client, starting from nothing	REST onboarding: POST /api/auth/register, verify-code, set-password, then the sandbox routes — see AI Agent Quickstart
Client cannot do remote OAuth MCP, or needs allowlisting by 6-digit code, browser handoff, or unmasked PII	Local server (recipient confirmation by emailed link needs none of this; it works over hosted OAuth, see Journey: sandbox then convert)
Bulk or marketing email to lists	The Communications Block. Over MCP, the main server already carries every Communications tool (the communications server is the narrow alternative; /ai-mcp-hosted): readiness, lists, contacts, templates, campaign drafts, tests, scheduling with an explicit yes from the person, and reports. It needs a plan that includes marketing email (Communications Block overview); its API and dashboard remain available. The domain tools are on the main server too (and on the narrow domains server). Permissions are staged: on the communications server the first consent covers reading and editing lists, contacts, templates and drafts, while on the main server the first marketing consent is read-only; adding a first sending identity asks for manage:comms.workspace, and scheduling asks for send:comms.campaign, each the first time it is needed. Tell the person before each; do not promise a single consent screen. Importing contacts: up to 1001 rows through the agent, bigger files by the person in the dashboard, opt-outs from a previous tool added as suppressions first (import rules). Never send marketing through a transactional Motor Block. The path is Journey E below.

On the packages: @motorical/cli is retired. It covered only onboarding and wrapped REST endpoints that remain, so the terminal-only path above is REST onboarding, not a CLI install. The local MCP server's own sandbox tools need a dashboard login token, which the REST steps above return directly (set-password returns a JWT and refresh token). Hosted MCP over OAuth is preferred whenever a person is present, because the agent never holds a secret at all.

Servers, scopes, and tools

Server	Scopes	Tools	Canonical URI
main	send:transactional, read:analytics, read:domains, manage:domains, manage:sandbox, manage:recipients, read:webhooks, manage:webhooks, manage:motor-blocks, read:comms, write:comms.content, write:comms.audience, manage:comms.audience, send:comms.campaign, manage:comms.workspace, manage:comms.webhooks	124	https://mcp.motorical.com/v1/motorical/mcp
transactional	send:transactional, read:analytics	7	https://mcp.motorical.com/v1/motorical_transactional/mcp
analytics	read:analytics	14	https://mcp.motorical.com/v1/motorical_analytics/mcp
domains	read:domains, manage:domains	11	https://mcp.motorical.com/v1/motorical_domains/mcp
sandbox	manage:sandbox, manage:recipients	9	https://mcp.motorical.com/v1/motorical_sandbox/mcp
webhooks	read:webhooks, manage:webhooks	8	https://mcp.motorical.com/v1/motorical_webhooks/mcp
motorBlocks	manage:motor-blocks	10	https://mcp.motorical.com/v1/motorical_motor_blocks/mcp
communications	read:comms, write:comms.content, write:comms.audience, manage:comms.audience, send:comms.campaign, manage:comms.workspace, manage:comms.webhooks	71	https://mcp.motorical.com/v1/motorical_communications/mcp
signup	none (unauthenticated)	1	https://mcp.motorical.com/v1/signup/mcp

Connect main for a full setup on one consent. Connect a narrow server instead when the task only needs one resource area — a token minted for one server's canonical URI is rejected by every other, so narrowing the server genuinely narrows what the connected client can do, not just what it's expected to do.

Choosing the starting path

Two ways to start, as equals: with the person's own domain, or on the Motorical-owned sandbox domain. The decision rule, the question to ask the person, and the one place that explains how both paths are limited are in Two ways to start. Then follow Journey: Free account with your own domain or Journey: sandbox then convert below. State the choice and the reason to the person; they may override it.

Rules

1. 202 is not delivered. A successful POST /v1/send means accepted for delivery, nothing more. Poll status or use motorical_wait_for_outcome for a terminal result before telling a human an email arrived.
2. Set dryRun: true while composing. Validate the payload first; only turn it off once you mean to send for real. HTTP POST /v1/send defaults to dryRun: false; the MCP tool motorical_send_email defaults to dryRun: true and also needs confirmRealSend: true. Always set dryRun explicitly.
3. Never ask the human for secrets in chat. An API key, password, or OAuth token typed into a chat message is a credential leak waiting to happen — use the signup handoff or the dashboard instead.
4. Ask for the narrowest scope that does the job, and say what each one means in plain language before requesting consent. manage:motor-blocks is not the same as send:transactional — don't request more than the task needs.
5. Deactivate is not delete. Deactivating a Motor Block is a reversible pause; deleting one is permanent and asynchronous. Restate the consequence before a human confirms either, and never treat them as interchangeable.
6. Choose a Motor Block by boundary, not by convenience. One Motor Block per project, ideally per sending domain — staging and production are separate Motor Blocks, not a flag on one.
7. Follow nextAction and error codes instead of retrying blind. A failure carries a stable machine- readable code (for example motor_block_limit_reached, domain_not_verified) and, where useful, a nextAction — read it before deciding what to do next.
8. Read live account state before acting. Call motorical_get_onboarding_state or motorical_list_motor_blocks first; the current OAuth grant is checked live on every call, never from a claim frozen in an old token.
9. Publish DNS records exactly as returned. A domain does not become sendReady until DKIM and SPF are both configured — re-check with motorical_domain_check_dns rather than assuming a DNS edit propagated.
10. Never ask for unmasked PII over a hosted OAuth grant. Recipient addresses are masked by default; includePII: true over OAuth returns a 403 by design — that boundary is intentional, not a bug to work around.
11. Never send marketing through a transactional Motor Block. The Communications Block is a separate product for bulk and marketing sends; mixing the two risks the transactional stream's deliverability.
12. cc, bcc, replyTo and attachments over HTTP: rolling out per Motor Block; SMTP always works. A Motor Block that has not been moved to the new sending path answers 422 with code feature_not_enabled and sends nothing (the fields are never silently dropped), so use SMTP there. Attachments are base64 in the request body and the plan decides them exactly as over SMTP. A transactional or general_purpose Motor Block sends attachments within the plan's limits (count, per-file size and per-message total; read them from GET /api/billing/plans, never quote them) under a platform ceiling on the whole encoded message. See Send attachments.

Marketing email rules

These sit beside the 12 rules above; rules 2 and 11 apply to marketing too. Journey E below is the path.

1. Look before acting. Read readiness, templates, brand kit, audience and settings first, and name the first missing thing.
2. Identity comes from the person. Never invent a sender name, postal address, logo, legal text or reply-to. Ask once; store it in the brand kit.
3. Consent is the person's decision. Do not state or imply that anyone subscribed. The footer reason line is written or approved by the person; so is an import's consent answer.
4. Test before any real send. Lint, preview with and without a name, check links, send a test (its links are placeholders, so the link check or a one-address list is the real proof), then preflight.
5. One confirmation tied to the exact action. The schedule summary (count, sender, subject, time and timezone) is what the person says yes to; a changed audience or template voids it.
6. Never "send now". A send is always scheduled at an explicit time, with a minimum lead time so there is time to cancel and a daily cap on schedules. Read the numbers from motorical://comms/limits-and-pacing, never from memory.
7. Scheduled is not delivered. Report only what the report tool says, with its denominators; opens are estimates, so lead with clicks.
8. Numbers come from tools. Counts, plans, prices and limits are read live, never quoted from memory.
9. Irreversible actions belong to the person. Deleting a list, template or campaign, erasing a contact, cancelling a campaign and removing a suppression need an explicit choice after the numbers are shown.
10. Honour opt-outs first. Suppressions are account-wide; add the previous tool's opt-outs before importing.
11. Never print addresses. Results are masked; use them as they come.

Journeys

Each journey below is real, validated content — every tool name in it is checked against the live MCP tool registry, the same gate that protects the rest of this site. The machine-readable version of everything below is agents.json.

Journey A — coding assistant adding email to an app

Route: local server (API keys) or the HTTP API directly.

1. Get a Motor Block API key (mk_live_...) from the dashboard, or start from the developer sandbox instead — see Journey C for a zero-credential start.
2. Dry-run the payload: motorical_send_email (or POST /v1/send) with dryRun: true.
3. Remove dryRun and send for real once the payload validates.
4. Check delivery status rather than assuming success: motorical_get_send_status, motorical_get_message, motorical_get_message_events, or motorical_wait_for_outcome for a terminal result.
5. Optional: register a webhook (motorical_webhook_create) for delivery/bounce/complaint events instead of polling — available on both the local server and hosted OAuth's dedicated webhooks server (read:webhooks/manage:webhooks scopes).

Journey B — operator agent running a customer's account over MCP

Route: hosted MCP over OAuth, with a person present for consent.

1. Connect to the hosted MCP server — main for a full setup on one consent, or a narrow scoped server for least privilege. The human sees a browser consent screen naming the requested scopes.
2. Read live account state before acting: motorical_get_onboarding_state, motorical_list_motor_blocks.
3. Operate within the granted scope: send email, read analytics (motorical_get_overview, motorical_get_deliverability), or manage Motor Blocks (motorical_motor_block_list, motorical_motor_block_create).
4. A consequential change — motorical_motor_block_change_type, motorical_motor_block_assign_domain, motorical_motor_block_deactivate, motorical_motor_block_delete — needs a second call with confirm: true after restating exactly what will happen; a form-based client just answers that through its UI instead of a second tool call, but the two-step shape is the same everywhere since @motorical/mcp 1.9.4. Deactivate is reversible; delete is permanent and asynchronous — never treat them as interchangeable.

Journey C — chat-client agent whose human has no account

Route: connect the main motorical server and authenticate it, then Journey B. The signup server is not this route; it is for apps that implement an OAuth client (Journey D).

1. Connect the main hosted server (https://mcp.motorical.com/v1/motorical/mcp) in your client and run the client's authenticate step. For Claude Code the exact steps are in Motorical MCP.
2. The browser opens the Motorical sign-in page. Human required: the person creates the account there (onboarding), sets up MFA (required, cannot be skipped), and presses Allow on the consent screen. Consent resumes by itself; nobody runs authenticate a second time. Say to the human: "A browser window opened. Create your Motorical account there, set up two-factor authentication (required for this connection), then press Allow. I never see or hold your credentials." Show any link to the human as a short markdown link with a plain label, never a bare long URL.
3. Continue as Journey B — the OAuth grant from consent is usable immediately, no separate step needed. The account starts on the unpaid developer sandbox, outbound-locked to an allowlist.
4. To send in production, convert the sandbox Motor Block onto a domain the human owns: motorical_sandbox_convert needs an active Motorical plan — it throws subscription_required with err.data.upgradeUrl if none exists yet; retry the same call once the human has subscribed. Say to the human: "To move off the sandbox onto your own domain, you'll need an active Motorical plan — here's the link to subscribe."
5. Add the domain and complete DNS verification before any production send is possible: motorical_domain_add returns the exact DNS records, motorical_domain_verify confirms ownership, motorical_domain_check_dns confirms DKIM/SPF are live. A domain is not sendReady until both are configured. Say to the human: "Add these DNS records at your domain registrar, then let me know once they're live so I can verify them."

Journey: sandbox then convert

Path 1. Route: hosted MCP over OAuth (main, or the sandbox server). Use it when the person is only trying things, has no domain yet, or no human is at the keyboard. The sandbox is a Motorical-owned .sandbox domain (instant, no DNS). Within it, a real send may reach only the account address and addresses that confirmed by link. Per sandbox Motor Block the caps are 20 messages a day and 5 an hour, and 50 real recipients a month (see Two ways to start).

1. motorical_get_onboarding_state — no plan and no domain returns the two options and a choose rule.
2. motorical_sandbox_provision — instant; the new Motor Block joins the live authorization.
3. motorical_sandbox_status — domain.sandbox true means the Motorical-owned domain; allowlist is the effective list of recipients.
4. motorical_free_recipient_add for each other recipient. Human required: the recipient must open the emailed link and click confirm; the tool never confirms for them. An authorization granted before the manage:recipients scope existed must be re-approved to include it.
5. motorical_send_email with dryRun: true, then for real to the account address or a confirmed recipient. Sends to anyone else are refused (sandbox_outbound_locked (a locked sandbox, the default) or sandbox_recipient_denied (after an explicit unlock)), over HTTP and SMTP alike.
6. motorical_wait_for_outcome — a 202 is not delivered.
7. Human required: the person subscribes to a plan (subscription_required carries an upgradeUrl).
8. motorical_sandbox_convert (confirmation required) onto a verified domain the person owns.

Journey: Free account with your own domain

Path 2. Route: hosted MCP over OAuth (main, or domains plus sandbox). Use it when the person has a domain whose DNS they control and want to keep. On a Free account, when automatic provisioning is enabled and the domain is fully verified, a sandbox Motor Block is created on that domain automatically once DKIM and SPF pass (otherwise call motorical_sandbox_provision); it runs under the same limits as Path 1 (see Two ways to start).

1. motorical_get_onboarding_state.
2. motorical_domain_add. A Free account may have one domain; a second returns free_domain_limit with a nextAction.
3. Human required: the person publishes the DNS records exactly as returned. Then motorical_domain_check_dns until the domain is send-ready (DKIM and SPF both pass).
4. The sandbox Motor Block appears on its own, with no provisioning call, on a Free account when automatic provisioning is enabled and the domain is fully verified. motorical_sandbox_status shows domain.sandbox false (your own domain). If no block appeared, motorical_sandbox_provision creates one on the Motorical-owned domain instead.
5. Human required, only if the account state reports grant_missing_sandbox: the current authorization predates that block, so the person reconnects (re-authorizes) the client.
6. motorical_free_recipient_add for each recipient. Human required: each recipient clicks the emailed link. An authorization granted before the manage:recipients scope existed must be re-approved to include it.
7. motorical_send_email (dry run first), then motorical_wait_for_outcome.
8. Human required: subscribe to a plan, then motorical_sandbox_convert (confirmation required).

Journey D — agent embedding Motorical in its own agent app

Not yet written. The OAuth client registration rules for an app's own client metadata document are unverified against the live hosted server (a test with a fake client id returned "client_id domain is not permitted") — writing real steps before that's settled would mean guessing at behavior nobody has confirmed. Use Journey A or B in the meantime. When this journey is written, the unauthenticated signup server (motorical_signup_handoff) belongs to it: it bridges a user with no account through signup and consent for an app that implements its own OAuth client.

Journey E — agent running marketing campaigns

Route: hosted MCP over OAuth, the main server (it carries every Communications tool) or the narrow communications server, with a person present for consent. The steps are numbered as in agents.json. Human required marks where the person supplies a fact, looks at something, or says yes.

1. Check the plan, then connect. Marketing email needs a plan that includes it (read motorical://docs/plans, or GET https://motorical.com/api/billing/plans if your client cannot read resources; never quote from memory), a verified sending domain and a marketing Motor Block assigned to the workspace. Tell the person which permission each later step asks for. Human required: consent.
2. Look first. motorical_whoami, comms_get_readiness, comms_get_map, comms_get_workspace_settings. Name the first missing thing, not the whole manual. Then go through the three workspace settings with the person once, using the explanations the tool returns: whether a click counts as consent (off by default), whether opens are tracked (on by default; open counts are estimates), and where people go after they unsubscribe. They apply to every campaign in the workspace and a campaign cannot override them. The person decides: never change one yourself, and change one only with comms_update_workspace_settings after a yes to its dry run (then preflight again). Human required: the three choices. A consent request ({{consent_url}}, a campaign created as a consent request) is separate from "a click counts as consent".
3. Check the sender. comms_list_marketing_blocks, motorical_domain_dns_records, motorical_domain_check_dns. Human required: DNS records on an unverified domain.
4. Bring the audience in. comms_import_contacts (dry run first), comms_create_list, comms_get_list. Human required: the consent basis of each source. Add the previous tool's opt-outs as suppressions first. Then read the audience with comms_audience_summary, comms_search_audience and comms_suppression_info before choosing the list.
5. Brand kit, template, check. comms_get_brand_kit, comms_set_brand_kit (dry run, then write), comms_list_starters, comms_create_template_from_starter (or comms_create_template when no starter fits), then comms_get_template_rules, comms_lint_template, comms_preview_template, comms_check_links, comms_suggest_template_fixes, comms_apply_template_fixes. Human required: sender name, postal address, language and the footer reason line in the person's own words. If no footer reason is given, the template still saves with a neutral "sent by" line and a footer_reason_default warning: say plainly that the footer then does not tell people why they are receiving the email, and offer to add the reason. Name every finding before offering a fix; apply one only with a yes.
6. Draft and preflight. comms_create_campaign, comms_preflight_campaign. Show the numbers exactly as returned, warnings first. A preflight goes stale after any change.
7. Test. comms_send_test or comms_send_template_test: one copy to the account owner only. Human required: looks at the inbox. Links in a test copy are placeholders, so do not ask the person to click the unsubscribe link in it; check the real links with comms_check_links on the template, or send a real campaign to a list holding one test address for the real path.
8. Schedule. comms_schedule_campaign. Ask for the timezone, read back one sentence naming the campaign, subject, sender, how many people and the time, and call again with the confirmation only after a clear yes to it.
9. Cancel if asked. comms_cancel_campaign at once if the person says stop. Cancelling is final.
10. Report. comms_get_campaign, comms_get_campaign_report, comms_get_campaign_timeline. Every count with what it is out of; opens are estimates; delivery outcomes may lag the hand-off.

Clean up after testing: test objects stay until removed. With the delete permission an agent can delete a template or a campaign (comms_delete_template, comms_delete_campaign; dry run first; a campaign goes to the recycle bin). A template stays locked while any campaign uses it, even one in the recycle bin. Otherwise the person removes them in the dashboard.

The Communications tools also offer six prompts that run parts of this journey and four reference resources under motorical://comms/ (limits and pacing, vocabularies, template rulebook, how sending works).

Journey F — operating and reporting on an account that already sends

Route: hosted MCP over OAuth, read-only tools (read:analytics, read:domains).

1. motorical_whoami: who the connection acts for and which scopes the grant holds.
2. motorical_list_motor_blocks: keep the ids.
3. motorical_get_overview, motorical_get_daily_summary for a window. A date-only to means that whole day (up to 23:59:59 UTC), as in the Communications tools; omit to for up to now.
4. motorical_get_error_codes, motorical_get_logs: failures by cause, then the messages behind a code.
5. motorical_get_deliverability, motorical_get_reputation, motorical_get_anomalies, motorical_domain_health.
6. Report the window, the Motor Blocks and anything hidden by a missing scope. Do not call a write tool while reporting; a change is a separate, confirmed action (Journey B).

Machine twin

Everything on this page that an agent needs to act on — the journeys, the scopes, human-required flags, and stop conditions — is also published as machine-readable JSON at docs.motorical.com/agents.json, generated from the same source this page renders from.

Related

• AI Agent Quickstart — the deep integration reference for Journey A
• Motorical MCP — the choice between local and hosted MCP
• Hosted MCP Resource Server — full scope and tool detail for Journey B
• Communications Block — for bulk and marketing sends (Journey E)