# Motorical SMTP Docs Motorical Sending SMTP is a transactional email API and SMTP provider for production apps: HTTP `POST /v1/send`, SMTP on `mail.motorical.com`, signed delivery webhooks, and one Motor Block per project. A Motorical SMTP Motor Block is an isolated sending stream for one project (app, staging, tenant, or experiment): its own domain, auth method, API keys, SMTP credentials, rates, logs, webhooks, and automation. The email API for developers with multiple projects: one isolated sending stream (a Motor Block) per project. Same job class as SendGrid / Postmark / Mailgun / Amazon SES-style transactional email APIs — with Motorical Motor Blocks for per-project isolation. Full peer mapping: https://docs.motorical.com/llms-full.txt · Compare: https://motorical.com/compare · Migrate from SendGrid: https://docs.motorical.com/guides/migrate-from-sendgrid · Migrate from Postmark: https://docs.motorical.com/guides/migrate-from-postmark Use Motorical SMTP when an app needs to send production transactional email, separate email streams by application/domain/environment/tenant, inspect delivery events, or automate delivery outcomes with webhooks. Important docs: - **Agent Hub (start here if you are an AI agent):** https://docs.motorical.com/agents — route chooser, rulebook, and journeys; machine twin at https://docs.motorical.com/agents.json - Connect your agent (start here to add Motorical to Claude, ChatGPT or Cursor: one address, one path per goal, what to approve now or later, what only the dashboard can do, and what to do when tools are missing): https://docs.motorical.com/connect-your-agent - AI Agent Quickstart: https://docs.motorical.com/ai - Latest changes (what changed in the API, dashboard and docs, newest first; machine twin https://docs.motorical.com/changelog.md; feeds https://docs.motorical.com/changelog/rss.xml, https://docs.motorical.com/changelog/atom.xml, https://docs.motorical.com/changelog/feed.json): https://docs.motorical.com/changelog - Motorical MCP Server: https://docs.motorical.com/ai-mcp - Marketing email / newsletters over MCP: these tools are on the main address, `https://mcp.motorical.com/v1/motorical/mcp`, once the person approves the marketing permissions (no second connector needed); a focused `communications` server, `https://mcp.motorical.com/v1/motorical_communications/mcp`, carries the same tools for an agent that should only do marketing email (readiness, lists, contacts, templates, campaign drafts, test sends, scheduling only on the person's explicit yes, reports). Needs a plan that includes marketing email (https://docs.motorical.com/communications/overview) and a sending domain verified on the `domains` server. Contact import: up to 1001 rows per JSON request; bigger files via the dashboard card Comm > Lists > Import Contacts (CSV), never through chat; add opt-outs from the old tool as suppressions first. Migrating from Mailchimp or another tool: https://docs.motorical.com/communications/migrating-from-mailchimp . Plans and prices change: read them live from the MCP resource motorical://docs/plans (or GET https://motorical.com/api/billing/plans), never from memory. Details: https://docs.motorical.com/communications/lists-and-subscribers#importing-contacts and https://docs.motorical.com/ai-mcp-hosted - MCP tool reference (every tool, its scope, servers, inputs; and which tools each grant can see; generated from the code): https://docs.motorical.com/ai-mcp-tools - Operate and report on a live account over MCP (journey; how to read the scopes you hold; whether an array in `to` is one message; how dates behave): https://docs.motorical.com/ai-mcp-live-account - MCP errors (every code a tool call can return, what it means, what an agent should do; branch on `code`): https://docs.motorical.com/ai-mcp-errors - MCP tool reference, one page per area (smaller than the full reference): https://docs.motorical.com/ai-mcp-tools-transactional , https://docs.motorical.com/ai-mcp-tools-analytics , https://docs.motorical.com/ai-mcp-tools-domains , https://docs.motorical.com/ai-mcp-tools-sandbox , https://docs.motorical.com/ai-mcp-tools-webhooks , https://docs.motorical.com/ai-mcp-tools-motor-blocks , https://docs.motorical.com/ai-mcp-tools-communications - MCP Cursor config template: https://docs.motorical.com/motorical-mcp.cursor.json - Developer sandbox onboarding journey (machine-readable): https://docs.motorical.com/onboarding-sandbox-journey.json - Connect MCP (hosted, nothing to install): in a terminal run `claude mcp add --transport http motorical https://mcp.motorical.com/v1/motorical/mcp`, then start a new Claude Code session and type `/mcp`, pick `motorical`, choose Authenticate, create your account in the browser (or first at https://motorical.com/register) (two-factor authentication is required), press Allow. Claude Desktop or Claude.ai: add a custom connector with the same URL. Other agents (ChatGPT, Codex, Cursor, VS Code, any MCP client) and which sign-in methods work: https://docs.motorical.com/ai-mcp-hosted#connect. The npm package `@motorical/mcp` is a different, local option for API-key setups; `@motorical/cli` is retired. - Which one do I use? Hosted MCP (default, no install, you create the account in the browser); agent-led onboarding over the HTTP API (no connector: the agent registers you from your email and the 6-digit code you read it, then hands you a one-time 90-second link to open the dashboard and set your own password); local npm package `@motorical/mcp` (only for API-key or stdio-only clients). Details: https://docs.motorical.com/ai-mcp#which-route - Pick your route: trying it or no domain yet -> Path 1 sandbox; own domain you will keep -> Path 2 Free account with your domain; on a plan -> convert and manage Motor Blocks; app code -> HTTP API or SMTP; building an OAuth client app -> `signup` server. Details: https://docs.motorical.com/ai-mcp - Developer sandbox flow: signup → verify → provision a Motorical-owned `.sandbox` domain (instant, no DNS), or add and fully verify your own domain and, on a Free account when automatic provisioning is enabled, get a sandbox Motor Block on it automatically once DKIM and SPF pass (otherwise call provision) → dry-run / allowlisted send → convert after a paid plan → `domain check-dns` / re-verify for sendReady → `/v1/send`. Choose by one rule and the hybrid limits explained at https://docs.motorical.com/ai#two-ways-to-start - Sandbox real sends to a recipient outside the allowlist are refused with `403` `sandbox_outbound_locked` (a locked sandbox, the default) or `sandbox_recipient_denied` (after an explicit unlock) (the body lists `denied` and `allowlist`), the same as over SMTP; they are never redirected. The old `sandboxRedirect` response field is deprecated and no longer returned. Add the recipient to the allowlist first (see below). - Recipient confirmation, which method where: hosted MCP = emailed link (`motorical_free_recipient_add`, the recipient clicks); 6-digit code = local server or REST with a dashboard session only. - Expand the sandbox allowlist by proving ownership of the address: `POST /api/developer/sandbox/allowlist/request` emails a 6-digit code, then `POST /api/developer/sandbox/allowlist/confirm` with `{ email, code }` (MCP tools `motorical_sandbox_allowlist_request` / `motorical_sandbox_allowlist_confirm`; these need a dashboard session). Over OAuth, a recipient confirms by emailed link through `motorical_free_recipient_add` with scope `manage:recipients`; an authorization granted before that scope existed must be re-approved to include it. - Sandbox credentials: over hosted OAuth, `motorical_sandbox_provision` never returns credentials. The new Motor Block is added to your authorization and the backend checks your CURRENT authorization on every call, so it is usable immediately by naming it with `motorBlockId` — no token refresh. `motorical_sandbox_convert` is a one-way production identity transition: you may pass a production `name` and `type`; the block keeps its id, password, API keys and auth method, but its SMTP username is REPLACED (response: `previousSmtpUsername`, `smtpUsername`, `integrationActionRequired`) and credentials are never returned inline — see `credentialsLocation` (dashboard link). The local stdio `@motorical/mcp` server (dashboard-JWT auth) still returns credentials directly — securing them is the customer's own responsibility on that path. Auth method (Password/API Key/OAuth 2.0/mTLS) is readable via `motorical_get_config`'s `activeAuthMethod` field; changing it is dashboard-only, not available over MCP. - Production Motor Block management (hosted MCP server `https://mcp.motorical.com/v1/motorical_motor_blocks/mcp`, scope `manage:motor-blocks`): `motorical_motor_block_list`, `_create` (verified non-sandbox domain, UUID v4 `idempotencyKey`, plan limit applies), `_rename` (display name only — never changes the SMTP username), `_change_type` (`transactional` ⇄ `general_purpose`, confirmed), `_assign_domain` (confirmed), `_deactivate` (reversible pause, confirmed), `_reactivate`, `_delete` (PERMANENT, asynchronous, irrecoverable; must be deactivated first; explicit `deleteHistory`; returns a `jobId`) and `_delete_status` (poll the `jobId`). Only `transactional`/`general_purpose` blocks are managed. A newly created block is usable at once by explicit `motorBlockId` (start with `dryRun: true`). Credentials are never returned over the hosted server. Deactivate is not delete. Stable error codes include `motor_block_limit_reached`, `domain_not_verified`, `motor_block_name_conflict`, `motor_block_must_be_inactive`, `motor_block_not_authorized`, `motor_block_id_conflict`. REST: `/api/public/v1/account/motor-blocks*` (see openapi.json tag Account Motor Blocks). - Onboarding auth JWT: access ~15m + refreshToken 7d; `POST /api/auth/refresh` with `{ refreshToken }` (OpenAPI tag Onboarding Auth) - Auth credential map (JWT vs `mk_live_` vs `ak_live_`): https://docs.motorical.com/api-reference/authentication · also `llms-full.txt` § Authentication - Send-ready: ownership verify alone is not enough — `POST /api/public/v1/domains/{id}/check-dns` (Public API bearer or MCP OAuth/Delegation) or `POST /api/domains/{id}/check-dns` (dashboard JWT) — either flips `dkim_configured`/`spf_configured` (403 `DOMAIN_DNS_INCOMPLETE` otherwise). Domains are account-wide, no Motor Block needed. - Display name: optional `fromName` on `POST /v1/send` (do not set From via headers). SMTP: set display name in the message `From:` header (`"Name" `). - Sandbox API: `GET/POST/PATCH /api/developer/sandbox*` (dashboard JWT; OpenAPI tag Developer Sandbox) - Send Email With HTTP API: https://docs.motorical.com/send-email/http-api-quickstart - SMTP Authentication Methods: https://docs.motorical.com/smtp-integration/authentication-methods - API Authentication: https://docs.motorical.com/api-reference/authentication - API Endpoints: https://docs.motorical.com/api-reference/endpoints - Webhooks: https://docs.motorical.com/api-reference/webhooks - Communications API Reference: https://docs.motorical.com/communications/api-reference - Isolate email streams with Motor Blocks: https://docs.motorical.com/guides/motor-block-separation - Full AI reference: https://docs.motorical.com/llms-full.txt - OpenAPI snapshot (docs): https://docs.motorical.com/openapi.json - Endpoint index (JSON): https://docs.motorical.com/api-documentation.json - Postman collection: https://docs.motorical.com/motorical-public-api.postman_collection.json - Postman environment: https://docs.motorical.com/motorical-public-api.postman_environment.json - Live OpenAPI (runtime): https://api.motorical.com/api/public/openapi.json - Swagger UI: https://api.motorical.com/api/public/docs - Motorical SMTP GitHub Examples: https://github.com/motorical-smtp/motorical-packages/tree/main/examples - Gluo Portal API (Business Mail Suite sibling): https://documents.gluo.eu/llms.txt SMTP submission (out-of-band protocol, not HTTP OpenAPI): - Host: mail.motorical.com - Ports: 2587 (STARTTLS), 2465 (implicit TLS) - Auth: password, OAuth 2.0 access token as password (or XOAUTH2), or mTLS + password - OAuth authorize: https://motorical.com/api/oauth2/authorize - OAuth token: https://motorical.com/api/oauth2/token Key integration rules: - Use `mk_live_...` Motorical SMTP Motor Block API Keys for `POST https://api.motorical.com/v1/send` (`Authorization: ApiKey mk_live_...` or `X-Api-Key`). - Use `ak_live_...` Account API Keys to mint short-lived Public API bearer tokens. - Use `Authorization: Bearer ...` for `/api/public/v1` logs, analytics, webhooks, exports, and configuration. - Use an `ak_live_...` Account API Key plus `X-Tenant-Id` for Communications Block operations. Discover the workspace/tenant ID with `GET https://api.motorical.com/api/comm/tenant` using the account key alone. - Do not use OAuth access tokens or Bearer tokens on `POST /v1/send`. - Do not use Motor Block API keys as SMTP passwords unless the block’s active method is configured for that (prefer dedicated SMTP password / OAuth / mTLS). - Start production send integrations with `dryRun: true`. - Which host serves what: the HTTP Send API (`/v1/*`) is served only by `https://api.motorical.com` (`https://motorical.com/v1/send` answers 405); the Public API (`/api/public/v1/*`) and the dashboard/auth API (`/api/*`) answer on both hosts, so use `https://api.motorical.com` for every API call. - `dryRun` defaults: HTTP `POST /v1/send` defaults to `dryRun: false` (the request is sent unless you pass `dryRun: true`). The MCP tool `motorical_send_email` defaults to `dryRun: true` and also needs `confirmRealSend: true` for a real send. Always set `dryRun` explicitly. - Checking delivery: the message-status routes (`GET /api/public/v1/messages/{id}`) need a separate bearer token with scope `logs.read`, not the `mk_live_` send key. Mint one with `POST /api/public/token` `{ motorBlockId, scopes: ["logs.read"] }` using the dashboard JWT (or `POST /api/public/token/account-key` with an `ak_live_` key). The hosted MCP's `motorical_wait_for_outcome` does this for you. - The browser hand-off link from `POST /api/auth/web-handoff` is short-lived (`expiresInSeconds` in the response): open it right away; if it says expired, ask for a new link or sign in with your password. - Verify webhook events with `X-Motorical-Signature`. Send quotas and 429 handling (POST /v1/send): - Two ceilings apply: a per-Motor-Block cap (burst/hourly/daily) and an account-wide cap (hourly/daily) across every Motor Block on the account. - Check headroom: GET https://api.motorical.com/api/public/v1/motor-blocks/{id}/rate-limits (per block) and GET https://api.motorical.com/api/public/v1/account/rate-limits (account-wide). Both need scope `usage.read`. - A refused send returns 429 with `error` set to `rate_limited_block`, `rate_limited_account`, or `rate_limited_warmup`, plus `retryAfterSeconds` in the body and a `Retry-After` header (seconds). - Enforced today: `rate_limited_block`. Measured but not yet refusing: `rate_limited_account`, `rate_limited_warmup`. Handle all three now. - A successful send carries `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` (the block's daily ceiling). They are absent on `dryRun`, on early validation failures, and when the limiter is unavailable — never read their absence as unlimited headroom. - `X-RateLimit-*` (with the `X-` prefix) is a different limiter: API requests per credential per minute, not emails. - SMTP submission shares the same counters and refuses with `451 4.7.1 Rate limit exceeded (): /. Retry in s.` - Full contract: https://docs.motorical.com/api-reference/rate-limits