MCP tool reference

What you are looking at: every tool of the Motorical MCP servers, and the one prompt, with what it does, the scope it needs, where it is available, what you pass in and a starting example. It is generated from the tool registry each time the documentation is built, so it lists 57 entries because the product has them, and a new tool cannot ship without an entry here. For how to connect and which server to pick see Hosted MCP and Local MCP; for what a connected agent should do on a live account see Operate and report on a live account.

What a grant can see

An OAuth grant holds scopes. A tool is listed to the agent only when the grant covers every scope the tool needs (an implied scope counts: manage:domains covers read:domains). Calling a tool that is not listed is refused with 403 insufficient_scope, so the list is a narrowing of what is advertised, never a loophole. The first table shows each tool against the servers that list it and says when a tool is hidden even from a grant that holds its scope; the second shows what a grant holding only one scope would see.

Tool	Scope needed	Listed on servers	Hidden when
motorical_send_email	send:transactional	main, transactional
motorical_get_message	read:analytics	main, transactional
motorical_get_message_events	read:analytics	main, transactional
motorical_wait_for_outcome	read:analytics	main, transactional
motorical_get_send_status	read:analytics	main, transactional
motorical_integrate_send	send:transactional	main, transactional
motorical_list_motor_blocks	read:analytics	main, analytics
motorical_get_overview	read:analytics	main, analytics
motorical_get_daily_summary	read:analytics	main, analytics
motorical_get_metrics	read:analytics	main, analytics
motorical_get_deliverability	read:analytics	main, analytics
motorical_get_reputation	read:analytics	main, analytics
motorical_get_anomalies	read:analytics	main, analytics
motorical_get_providers	read:analytics	main, analytics
motorical_get_error_codes	read:analytics	main, analytics
motorical_get_rate_limits	read:analytics	main, analytics
motorical_get_account_rate_limits	read:analytics	main, analytics
motorical_get_onboarding_state	read:analytics	main, analytics
motorical_whoami	No scope	main, transactional, analytics, domains, sandbox, webhooks, motorBlocks
motorical_get_logs	read:analytics	main, analytics
motorical_get_message_by_smtp_id	read:analytics	main, analytics
motorical_domain_list	read:domains	main, domains
motorical_domain_get	read:domains	main, domains
motorical_domain_dns_records	read:domains	main, domains
motorical_domain_health	read:domains	main, domains
motorical_domain_add	manage:domains	main, domains
motorical_domain_verify	manage:domains	main, domains
motorical_domain_check_dns	manage:domains	main, domains
motorical_get_config	read:domains	main, domains
motorical_get_domain_health	read:domains	main, domains
motorical_sandbox_status	manage:sandbox	main, sandbox	Hidden once the account is past the sandbox phase
motorical_sandbox_provision	manage:sandbox	main, sandbox	Hidden once the account is past the sandbox phase
motorical_sandbox_convert	manage:sandbox	main, sandbox	Hidden once the account is past the sandbox phase
motorical_sandbox_allowlist_request	manage:sandbox	main, sandbox	Never listed over OAuth (dashboard session only)
motorical_sandbox_allowlist_confirm	manage:sandbox	main, sandbox	Never listed over OAuth (dashboard session only)
motorical_free_recipient_add	manage:recipients	main, sandbox	Hidden once the account is past the sandbox phase
motorical_free_recipient_list	manage:recipients	main, sandbox	Hidden once the account is past the sandbox phase
motorical_free_recipient_remove	manage:recipients	main, sandbox	Hidden once the account is past the sandbox phase
motorical_webhook_list	read:webhooks	main, webhooks
motorical_webhook_create	manage:webhooks	main, webhooks
motorical_webhook_update	manage:webhooks	main, webhooks
motorical_webhook_delete	manage:webhooks	main, webhooks
motorical_webhook_test	manage:webhooks	main, webhooks
motorical_webhook_get_deliveries	read:webhooks	main, webhooks
motorical_webhook_get_stats	read:webhooks	main, webhooks
motorical_motor_block_list	manage:motor-blocks	main, motorBlocks
motorical_motor_block_create	manage:motor-blocks	main, motorBlocks
motorical_motor_block_rename	manage:motor-blocks	main, motorBlocks
motorical_motor_block_change_type	manage:motor-blocks	main, motorBlocks
motorical_motor_block_assign_domain	manage:motor-blocks	main, motorBlocks
motorical_motor_block_deactivate	manage:motor-blocks	main, motorBlocks
motorical_motor_block_reactivate	manage:motor-blocks	main, motorBlocks
motorical_motor_block_delete	manage:motor-blocks	main, motorBlocks
motorical_motor_block_delete_status	manage:motor-blocks	main, motorBlocks

Scope granted on its own	Also covers	Tools listed	Which
send:transactional	nothing	3	motorical_send_email, motorical_integrate_send, motorical_whoami
read:analytics	nothing	19	motorical_get_message, motorical_get_message_events, motorical_wait_for_outcome, motorical_get_send_status, motorical_list_motor_blocks, motorical_get_overview, motorical_get_daily_summary, motorical_get_metrics, motorical_get_deliverability, motorical_get_reputation, motorical_get_anomalies, motorical_get_providers, motorical_get_error_codes, motorical_get_rate_limits, motorical_get_account_rate_limits, motorical_get_onboarding_state, motorical_whoami, motorical_get_logs, motorical_get_message_by_smtp_id
read:domains	nothing	7	motorical_whoami, motorical_domain_list, motorical_domain_get, motorical_domain_dns_records, motorical_domain_health, motorical_get_config, motorical_get_domain_health
manage:domains	read:domains	10	motorical_whoami, motorical_domain_list, motorical_domain_get, motorical_domain_dns_records, motorical_domain_health, motorical_domain_add, motorical_domain_verify, motorical_domain_check_dns, motorical_get_config, motorical_get_domain_health
manage:sandbox	nothing	4	motorical_whoami, motorical_sandbox_status, motorical_sandbox_provision, motorical_sandbox_convert
manage:recipients	nothing	4	motorical_whoami, motorical_free_recipient_add, motorical_free_recipient_list, motorical_free_recipient_remove
read:webhooks	nothing	4	motorical_whoami, motorical_webhook_list, motorical_webhook_get_deliveries, motorical_webhook_get_stats
manage:webhooks	read:webhooks	8	motorical_whoami, motorical_webhook_list, motorical_webhook_create, motorical_webhook_update, motorical_webhook_delete, motorical_webhook_test, motorical_webhook_get_deliveries, motorical_webhook_get_stats
manage:motor-blocks	nothing	10	motorical_whoami, motorical_motor_block_list, motorical_motor_block_create, motorical_motor_block_rename, motorical_motor_block_change_type, motorical_motor_block_assign_domain, motorical_motor_block_deactivate, motorical_motor_block_reactivate, motorical_motor_block_delete, motorical_motor_block_delete_status

Every tool

motorical_get_send_status

Check Send API status. Check Motorical transactional email HTTP Send API status (GET /v1/status). No auth required. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, transactional; the local server too
Acts on	See the description
REST route	GET /v1/status
Behaviour	Read-only; safe to repeat

No inputs.

Returns a structured result with the fields success, message, data.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_mint_public_token

Mint public API token. Mint a short-lived Public Analytics API bearer token using MOTORICAL_AK_API_KEY (ak_live_...) or, when none is configured, MOTORICAL_JWT. Use for /api/public/v1 logs, analytics, webhooks, config. Not for POST /v1/send.

Property	Value
Needs scope	No OAuth scope (uses an operator credential)
Available on	Local server only (it needs a credential from the environment, so no hosted OAuth server lists it)
Acts on	One Motor Block (the motorBlockId input)
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Defaults to MOTORICAL_MOTOR_BLOCK_ID
scopes	array of string	No	-
ttlSeconds	integer	No	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_list_motor_blocks

List Motor Blocks. List Motor Blocks (isolated sending streams) visible to a Public API bearer token (auto-mints with ak_live_ if needed). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/motor-blocks
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. Listing is account-wide; a block is only used when minting a legacy public token on the non-OAuth path.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_motor_block_list

List production Motor Blocks. List ordinary production Motor Blocks (isolated sending streams) this account can manage. Includes inactive blocks so they can be reactivated; excludes sandboxes, marketing, and portal-managed companion blocks. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/motor-blocks
Behaviour	Read-only; safe to repeat

No inputs.

Returns a structured result with the fields success, data.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_motor_block_create

Create production Motor Block. Create a production Motor Block on a verified customer domain. Use transactional for triggered, user-specific mail; use general_purpose for mixed operational sending. Hosted OAuth never returns passwords or API-key secrets. A UUID-v4 idempotencyKey makes retries return the original result. The domainId must be a verified, non-sandbox domain the account owns; a narrow Motor Blocks server cannot list or add domains, so get it from motorical_domain_list (on the main server, or the Domains server); add and verify one first with motorical_domain_add / motorical_domain_verify if the account has none. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/account/motor-blocks
Behaviour	Changes data

Input	Type	Required	Meaning
name	string	Yes	-
domainId	string (uuid)	Yes	Id of a verified, non-sandbox domain from motorical_domain_list (Domains server).
type	one of transactional, general_purpose	No	-
description	string	No	-
idempotencyKey	string (uuid)	Yes	Required UUID v4 for hosted creation; reused unchanged on retry.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{"name":"<name>","domainId":"<domainId>","idempotencyKey":"<idempotencyKey>"}

motorical_motor_block_rename

Rename Motor Block. Rename a production Motor Block for display and organization. This never changes its SMTP username, password, API keys, or auth method. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	PATCH /api/public/v1/account/motor-blocks/{id}/name
Behaviour	Changes data; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.
name	string	Yes	-

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{"name":"<name>"}

motorical_motor_block_change_type

Change Motor Block type. Change a production Motor Block between transactional and general_purpose. This changes the intended traffic classification, not credentials. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	PATCH /api/public/v1/account/motor-blocks/{id}/type
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.
type	one of transactional, general_purpose	Yes	-
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{"type":"transactional"}

motorical_motor_block_assign_domain

Assign Motor Block domain. Assign a different verified production domain to a Motor Block. The block is reactivated on the new domain; verify sendReady before sending. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /api/public/v1/account/motor-blocks/{id}/assign-domain
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.
domainId	string (uuid)	Yes	-
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_motor_block_deactivate

Deactivate Motor Block. Deactivate (pause) a production Motor Block. This is reversible and does not delete history or credentials; sending stops until reactivated. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /api/public/v1/account/motor-blocks/{id}/deactivate
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_motor_block_reactivate

Reactivate Motor Block. Reactivate a previously deactivated production Motor Block. A verified production domain is required. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /api/public/v1/account/motor-blocks/{id}/reactivate
Behaviour	Changes data; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_motor_block_delete

Permanently delete Motor Block. Permanently delete an inactive Motor Block asynchronously. This is irrecoverable. Set deleteHistory explicitly; then poll the returned job with motorical_motor_block_delete_status. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	DELETE /api/public/v1/account/motor-blocks/{id}
Behaviour	Destructive: asks the person to confirm

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Motor Block id from motorical_motor_block_list or create; optional only when the authorization has exactly one block.
deleteHistory	boolean	Yes	Whether delivery logs/events may also be permanently deleted.
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns a structured result with the fields success, data, message.

Example arguments (placeholders in angle brackets, required inputs only):

{"deleteHistory":true}

motorical_motor_block_delete_status

Get Motor Block deletion status. Read the current state and final report for an asynchronous permanent Motor Block deletion job. Requires OAuth scope: manage:motor-blocks (List and manage the ordinary lifecycle of production Motor Blocks: create, rename, change type, assign domain, deactivate, reactivate, and delete. Includes no credential values and cannot change the active auth method.).

Property	Value
Needs scope	manage:motor-blocks
Available on	Hosted servers: main, motorBlocks; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/motor-block-deletions/{jobId}
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
jobId	string (uuid)	Yes	-

Returns a structured result with the fields success, data.

Example arguments (placeholders in angle brackets, required inputs only):

{"jobId":"<jobId>"}

motorical_send_email

Send transactional email. Transactional email: send or validate via POST /v1/send. Over the hosted OAuth server your grant authorizes the send, so no key is needed and you never see one; the local stdio server instead needs MOTORICAL_MK_API_KEY (mk_live_...). Defaults to dryRun:true. Real sends require dryRun:false AND confirmRealSend:true. For developer-sandbox accounts, a non-allowlisted recipient is refused with 403 sandbox_outbound_locked (a locked sandbox, the default) or sandbox_recipient_denied (after an explicit unlock); it is never redirected, so add the recipient to the allowlist first. Real sends from a sandbox block go only to the effective allowlist (see motorical_sandbox_status); unlock a recipient with motorical_free_recipient_add (needs manage:recipients; the recipient must click the emailed link). A real send returns two different ids: messageId (use it with motorical_get_message and motorical_get_message_events) and nextAction.args.taskId (use it ONLY with motorical_wait_for_outcome). Neither works in the other tool. A dryRun does not send; for a sandbox block its answer reports sandboxPreview.wouldRefuse (recipients a real send would refuse). Optional cc, bcc and replyTo: cc recipients are named in the Cc header, bcc recipients receive the message but are named in no header, replyTo sets Reply-To. to, cc and bcc together take at most 50 recipients and every one is checked like a to recipient (sandbox allowlist, Free-account rules, suppression; a suppressed cc/bcc is skipped and listed in data.skipped). These fields are rolling out per Motor Block: a block that does not have them yet answers 422 feature_not_enabled and sends nothing, so retry without them or tell the person. Optional headers: an object of extra email headers, for threading a reply (In-Reply-To and References, copied from the message you answer), List-Unsubscribe (with List-Unsubscribe-Post for one-click) or your own X- headers; at most 20, no line breaks in values. Headers that would let a message pretend to be someone else or break the platform (From, Sender, Return-Path, To, Cc, Bcc, Subject, Date, Message-ID, MIME and Content-* headers, DKIM and authentication headers, X-Motorical-*) are refused with 400 DISALLOWED_HEADERS and nothing is sent. Set the reply address with replyTo or with a Reply-To header, not both. Optional attachments, for SMALL files only because the bytes travel through the conversation: a list of { filename, content (base64), contentType?, contentId?, disposition? }, at most 5 files and about 500 KB of files in total (700000 base64 characters). For anything larger, send over SMTP instead (the attachments guide in the docs). An inline image takes a contentId and disposition inline, and html references it as cid:<contentId>. Attachments roll out per Motor Block like cc and bcc: a block without them answers 422 feature_not_enabled and sends nothing. The plan decides how many files, how large and which types, exactly as over SMTP, and a refusal names the plan and the limit (413 attachment_too_large or attachments_total_too_large, 422 too_many_attachments, attachment_type_not_allowed, content_policy_rejected). A dryRun with attachments runs the same plan check without sending, but it does not run the virus and content scan, so a real send can still be refused for the file itself. from must be an address at the domain your Motor Block is assigned to: a verified, send-ready domain you own, or the Motorical-owned sandbox domain that motorical_sandbox_provision created (see motorical_get_onboarding_state sendFrom); any local part works. Requires OAuth scope: send:transactional (Send transactional email through the caller's Motor Block(s).).

Property	Value
Needs scope	send:transactional
Available on	Hosted servers: main, transactional; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /v1/send
Behaviour	Changes data

Input	Type	Required	Meaning
from	string (email)	No	Defaults to MOTORICAL_DEFAULT_FROM
fromName	string	No	Optional From display name (do not put From in headers — use this field)
to	string (email) or array of string	Yes	-
cc	string (email) or array of string	No	Copy recipients (Cc header). Rolling out per Motor Block: 422 feature_not_enabled where not available
bcc	string (email) or array of string	No	Blind-copy recipients: delivered, named in no header. Rolling out per Motor Block
replyTo	string (email)	No	Reply-To address. Do not also set a Reply-To header. Rolling out per Motor Block
headers	object (key/value map)	No	Extra email headers, e.g. In-Reply-To / References to thread a reply, List-Unsubscribe, X-* of your own. The platform refuses From, Sender, To, Cc, Bcc, Subject, Date, Message-ID, Content-, DKIM/authentication and X-Motorical- (400 DISALLOWED_HEADERS)
attachments	array of object	No	Small files to attach (base64). Rolling out per Motor Block: 422 feature_not_enabled where not available
subject	string	Yes	-
text	string	No	-
html	string	No	-
dryRun	boolean	No	Default true — validate without queueing
confirmRealSend	boolean	No	Required true when dryRun is false
idempotencyKey	string	No	-
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns a structured result with the fields success, dryRun, idempotent, message, messageId, status, delivered, nextAction, data.

Example arguments (placeholders in angle brackets, required inputs only):

{"to":"<to>","subject":"<subject>"}

motorical_wait_for_outcome

Wait for delivery outcome. Wait for a real send's actual delivery outcome (not just the 202 acceptance). Bounded server-side wait with backoff, capped under typical client timeouts. If the result is still_pending, wait retryAfterMs and call this again with the same taskId. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, transactional; the local server too
Acts on	See the description
REST route	GET /api/public/v1/messages/{id}/recipients
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
taskId	string	Yes	From motorical_send_email's nextAction after a real (non-dryRun) send
includePII	boolean	No	Return unmasked recipient addresses. Requires the logs.pii scope; default false (masked).

Returns a structured result with the fields status, retryAfterMs, result.

Example arguments (placeholders in angle brackets, required inputs only):

{"taskId":"<taskId>"}

motorical_get_message

Get message by ID. Get a message by send UUID (GET /api/public/v1/messages/{id}). Auto-mints bearer if needed. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, transactional; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/messages/{id}
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
messageId	string (uuid)	Yes	-
includePII	boolean	No	-
motorBlockId	string (uuid)	No	-

Returns a structured result with the fields success, data.

Example arguments (placeholders in angle brackets, required inputs only):

{"messageId":"<messageId>"}

motorical_get_message_events

Get message delivery events. Get delivery lifecycle events for a message (GET /api/public/v1/messages/{id}/events). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, transactional; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/messages/{id}/events
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
messageId	string (uuid)	Yes	-
includePII	boolean	No	-
motorBlockId	string (uuid)	No	-

Returns a structured result with the fields success, data.

Example arguments (placeholders in angle brackets, required inputs only):

{"messageId":"<messageId>"}

motorical_sandbox_status

Get developer sandbox status. Get developer sandbox status (domain, Motor Block, outbound lock, allowlist). Check data.stage to determine provisioning state: "not_started" (no sandbox yet — call motorical_sandbox_provision), "sandbox_active" (sandbox exists, outbound-locked), or "live" (converted to production, no lock). allowlist/caps are always present in the response regardless of stage — do not infer provisioning state from their presence. The allowlist is the EFFECTIVE list: sandbox recipients, link-confirmed recipients, the account address and the test sink, minus any address that clicked stop. domain.sandbox true means the Motorical-owned sandbox domain; domain.sandbox false means your own domain. outboundLocked true means real sends are limited to the allowlist, not that nothing can be sent; outboundLocked is null when no sandbox exists yet (nothing to lock). Requires OAuth scope: manage:sandbox (Check, provision, and convert the developer sandbox. Allowlisting by 6-digit code is dashboard-only and not available over OAuth; to allow recipients over OAuth use the manage:recipients scope.).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/sandbox
Behaviour	Read-only; safe to repeat

No inputs.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_sandbox_allowlist_request

Request sandbox allowlist addition. NOT AVAILABLE over hosted OAuth (dashboard session only): use motorical_free_recipient_add instead. Request to add a new recipient to the developer sandbox outbound allowlist. Sends a 6-digit confirmation code to that address (not the account owner) — call motorical_sandbox_allowlist_confirm with the code the recipient receives. Requires MOTORICAL_JWT. Requires OAuth scope: manage:sandbox (Check, provision, and convert the developer sandbox. Allowlisting by 6-digit code is dashboard-only and not available over OAuth; to allow recipients over OAuth use the manage:recipients scope.). Needs a dashboard session, not OAuth — granting this scope does not make this tool callable over a hosted OAuth/Delegation connection.

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	See the description
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>"}

motorical_sandbox_allowlist_confirm

Confirm sandbox allowlist code. NOT AVAILABLE over hosted OAuth (dashboard session only): use motorical_free_recipient_add instead. Confirm a sandbox allowlist recipient using the 6-digit code sent by motorical_sandbox_allowlist_request. On success the address is added to the allowlist and can receive real (non-dryRun) sandbox sends. Requires MOTORICAL_JWT. Requires OAuth scope: manage:sandbox (Check, provision, and convert the developer sandbox. Allowlisting by 6-digit code is dashboard-only and not available over OAuth; to allow recipients over OAuth use the manage:recipients scope.). Needs a dashboard session, not OAuth — granting this scope does not make this tool callable over a hosted OAuth/Delegation connection.

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	See the description
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-
code	string	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>","code":"<code>"}

motorical_sandbox_provision

Provision developer sandbox. Provision the unpaid developer sandbox on a Motorical-owned .sandbox domain (Path 1: instant, no DNS) with an outbound-locked Motor Block. A Free account that adds and fully verifies its own domain (Path 2) gets a sandbox Motor Block on that domain automatically once DKIM and SPF pass, with no provisioning call, when automatic provisioning is enabled; if none appears on its own, call this tool (it creates one on the Motorical-owned domain). Over hosted OAuth, this NEVER returns credentials -- the response has credentialsAvailable:false instead. The new Motor Block is added to the live authorization and is immediately usable by explicit id, without refreshing an access token minted before provisioning. Credentials become available via a dashboard link after motorical_sandbox_convert. Only the local @motorical/mcp stdio server (dashboard-JWT auth) still returns mk_live_ once, since it is the customer's own long-running process on their own infrastructure -- securing whatever it returns is the customer's own responsibility on that path. Requires OAuth scope: manage:sandbox (Check, provision, and convert the developer sandbox. Allowlisting by 6-digit code is dashboard-only and not available over OAuth; to allow recipients over OAuth use the manage:recipients scope.).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/account/sandbox/provision
Behaviour	Changes data

Input	Type	Required	Meaning
handle	string	No	-
channel	one of cli, agent, web	No	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_sandbox_convert

Convert sandbox to production. Convert sandbox Motor Block onto a verified customer domain (the target must be a verified real domain, never a .sandbox domain). A sandbox that already sits on your own verified domain converts onto that same domain, which needs no DNS change. Requires an active Motorical plan -- if none exists, this call throws with err.data.code === "subscription_required" and err.data.upgradeUrl naming where a human can subscribe; retry this same call once they have. If no sandbox exists yet (check motorical_sandbox_status first -- data.stage: "not_started"), call motorical_sandbox_provision instead; this endpoint returns 404 "No developer sandbox to convert" otherwise. The response always includes activeAuthMethod (the Motor Block's configured auth method -- "Password", "API Key", "OAuth 2.0", or "mTLS" -- read-only, changing it is dashboard-only). Conversion is a production identity transition: choose name/type or accept backend defaults; the SMTP username changes, so SMTP clients must be updated, while the existing SMTP password, API keys, and auth method remain unchanged. Over hosted OAuth it also includes credentialsLocation, a link to the dashboard where the customer can view or regenerate the actual credential value -- this tool never returns the raw value itself. Requires OAuth scope: manage:sandbox (Check, provision, and convert the developer sandbox. Allowlisting by 6-digit code is dashboard-only and not available over OAuth; to allow recipients over OAuth use the manage:recipients scope.).

Property	Value
Needs scope	manage:sandbox
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/account/sandbox/convert
Behaviour	Destructive: asks the person to confirm

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
name	string	No	-
type	one of transactional, general_purpose	No	-
confirm	boolean	No	Supplied as true only after the human confirms the exact displayed action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_free_recipient_add

Ask a recipient to allow test email. Ask a person to allow test email from this account. Sends them a confirmation email with a link; THEY must open it and click the button, and this tool never confirms on their behalf. Until they confirm, a sandbox allowlist refuses sends to that address, and so do the non-sandbox Motor Blocks of a Free account (when Free enforcement is on); a paid account is not affected. Their address is then also allowed for the sandbox. A recipient who clicked "stop" cannot be re-requested; the response is identical either way. The response includes data.recipient with the address and its status (pending until they click, or confirmed if already confirmed); a person must still click the emailed link. Requires OAuth scope manage:recipients (separate from manage:sandbox; an existing sandbox authorization must be re-approved to include it). Requires OAuth scope: manage:recipients (Request permission to send test email to an address you name, and see which addresses have confirmed or stopped. The recipient confirms by clicking an emailed link; an agent can never confirm on their behalf.).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/account/free-recipients
Behaviour	Changes data

Input	Type	Required	Meaning
email	string (email)	Yes	-

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"email":"<email>"}

motorical_free_recipient_list

List allowed test recipients. List the addresses this account has asked to allow test email, with each status (pending, confirmed or stopped), the recipient limit and current usage. The hourly, daily and monthly numbers are the Free-plan caps for non-sandbox Motor Blocks (see limitsNote in the response); a sandbox Motor Block is governed by the sandbox caps shown in motorical_sandbox_status. Requires OAuth scope manage:recipients. Requires OAuth scope: manage:recipients (Request permission to send test email to an address you name, and see which addresses have confirmed or stopped. The recipient confirms by clicking an emailed link; an agent can never confirm on their behalf.).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/free-recipients
Behaviour	Read-only; safe to repeat

No inputs.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_free_recipient_remove

Remove a test recipient. Remove an address from this account's test recipients, by the id returned from motorical_free_recipient_list. Requires OAuth scope manage:recipients. Requires OAuth scope: manage:recipients (Request permission to send test email to an address you name, and see which addresses have confirmed or stopped. The recipient confirms by clicking an emailed link; an agent can never confirm on their behalf.).

Property	Value
Needs scope	manage:recipients
Available on	Hosted servers: main, sandbox; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	DELETE /api/public/v1/account/free-recipients/{id}
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
id	string (uuid)	Yes	Recipient id from motorical_free_recipient_list
confirm	boolean	No	Required: true. Confirms this destructive action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"id":"<id>"}

motorical_domain_add

Add a customer domain. Add a customer domain (POST /api/domains). Returns verification DNS instructions. For cname_managed DKIM publish the CNAME in verification.records.dkim / dnsRecords (not a TXT p= key). On 409 (domain already registered), call motorical_domain_list first to check whether it is already on this account before asking the user to resolve the conflict. A Free account may have one domain; adding another returns free_domain_limit with a nextAction. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (Add, verify, and read sending domains and their DNS health. Includes everything read:domains grants.).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/domains
Behaviour	Changes data

Input	Type	Required	Meaning
domain	string	Yes	-
verificationMethod	one of dns, email	No	-
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.
idempotencyKey	string	No	Optional. Pass the same value on a retry to get the exact original response back, instead of a duplicate.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domain":"<domain>"}

motorical_domain_list

List account domains. List domains already on this account (GET /api/domains) — id, domain, verified, DNS auth flags. Call this before motorical_domain_add on a 409 conflict to self-diagnose whether the domain is already yours (proceed with the existing id) or genuinely owned by someone else (stop, do not guess). Over hosted OAuth it needs the read:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/domains
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_domain_get

Get one account domain. One domain on this account by id (GET /api/public/v1/domains/{id}): verified, DNS auth flags, DKIM mode, created. Read-only; no keys or tokens. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/domains/{id}
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_domain_dns_records

Get domain DNS records. The DNS records to publish for one domain, with what each is for (GET /api/public/v1/domains/{id}/dns-records). Pass lookup:true to also check what DNS currently answers (slower: live lookups). Read-only. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/domains/{id}/dns-records
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
lookup	boolean	No	Also run live DNS lookups for each record (default false)
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_domain_health

Get domain health by domain. Email-authentication health of ONE domain by id (GET /api/public/v1/domains/{id}/health): SPF, DKIM, DMARC, status, issues, and whether the answer is cached (source). Works for a domain that has no Motor Block yet. Same shape as motorical_get_domain_health, which answers for the domain attached to one Motor Block. Pass refresh:true for a live DNS check (slower). Read-only. Over hosted OAuth it needs the read:domains scope. Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/domains/{id}/health
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
refresh	boolean	No	Run a live DNS check instead of serving the cache (default false)
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_domain_verify

Verify domain ownership. Verify domain ownership and refresh DKIM/SPF/DMARC send-readiness flags (POST /api/domains/{id}/verify). Requires confirm:true — this call is destructive/consequential. Returns sendReady. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (Add, verify, and read sending domains and their DNS health. Includes everything read:domains grants.).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/domains/{id}/verify
Behaviour	Destructive: asks the person to confirm

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
method	one of dns, email	No	-
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.
confirm	boolean	No	Required: true. Confirms this destructive action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_domain_check_dns

Live-check domain DNS. Live-check DKIM/SPF/DMARC and persist dkim_configured/spf_configured (POST /api/domains/{id}/check-dns). Required before /v1/send when ownership is verified but send returns DOMAIN_DNS_INCOMPLETE. Over hosted OAuth it needs the manage:domains scope; the local server uses MOTORICAL_JWT. Requires OAuth scope: manage:domains (Add, verify, and read sending domains and their DNS health. Includes everything read:domains grants.).

Property	Value
Needs scope	manage:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	POST /api/public/v1/domains/{id}/check-dns
Behaviour	Changes data; safe to repeat

Input	Type	Required	Meaning
domainId	string (uuid)	Yes	-
recordType	one of dkim, spf, dmarc, mx	No	-
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"domainId":"<domainId>"}

motorical_web_handoff

Create browser handoff link. Mint a one-time browser handoff URL (POST /api/auth/web-handoff). Open the URL so the human can set a dashboard password / use the UI. Requires MOTORICAL_JWT. Give the person the link as a short markdown link such as [Open your Motorical dashboard](url), never as a bare long URL. The link is short-lived (the response has expiresInSeconds): open it right away; if it says expired, ask for a new link or sign in with your password.

Property	Value
Needs scope	No OAuth scope (uses an operator credential)
Available on	Local server only (it needs a credential from the environment, so no hosted OAuth server lists it)
Acts on	See the description
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
path	string	No	Optional in-app path after handoff, e.g. /usage

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_signup_handoff

Bridge a new user to signup + OAuth consent. FOR APPS THAT IMPLEMENT AN OAUTH CLIENT (hosts, embedded agent apps) -- NOT for chat agents. It needs your own client's OAuth values (clientId, a registered redirectUri, PKCE codeChallenge, resource); if you are an agent in Claude Code, Claude Desktop or another chat client you cannot supply them, so do not invent them: connect the main motorical server and authenticate it instead (the browser opens the sign-in page, the person creates the account and sets up MFA there, then authenticates again to reach consent). Bridge a human with no Motorical account onto this OAuth client (POST /api/auth/signup-handoff). Call with no continuationToken first: returns a one-time URL for the human to open in a browser, which runs signup if needed and then the normal OAuth consent screen for this client -- one browser visit gets them to a usable session. No credential is ever returned by this tool. Call again with the continuationToken once the human says they are done; status stays awaiting_browser until the account is verified with a password set. Only ever reachable on the unauthenticated signup audience (mcp.motorical.com/v1/signup/mcp) -- every other server requires a bearer already.

Property	Value
Needs scope	No OAuth scope (uses an operator credential)
Available on	The hosted signup server only (no sign-in needed)
Acts on	See the description
REST route	None
Behaviour	Changes data

Input	Type	Required	Meaning
clientId	string	No	Required on the first call: this CIMD OAuth client's https:// client_id.
redirectUri	string	No	Required on the first call: must match one of clientId's registered redirect_uris.
resource	string	No	Required on the first call: the RFC 8707 resource (canonical MCP server URI) the agent ultimately wants a token for.
codeChallenge	string	No	Required on the first call: PKCE code_challenge.
codeChallengeMethod	the value "S256"	No	Required on the first call: PKCE method, always S256.
scope	string	No	-
state	string	No	-
continuationToken	string	No	From a prior call's response. Present this instead of the other fields to check status.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_overview

Get Motor Block overview. Sending overview for one Motor Block over a date range — volume, delivery and bounce rates, and current usage against plan limits (GET /api/public/v1/motor-blocks/{id}/overview). Its reputation block is the same delivery reputation score as motorical_get_reputation. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/overview
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_daily_summary

Get daily send summary. Per-day send counts and outcomes for one Motor Block (GET /api/public/v1/motor-blocks/{id}/daily-summary). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/daily-summary
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
days	integer	No	How many days back, counting today

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_metrics

Get send metrics. Time-series send metrics for one Motor Block, bucketed by hour or day (GET /api/public/v1/motor-blocks/{id}/metrics). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/metrics
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive
interval	one of hour, day	No	Bucket size; defaults to the API default

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_deliverability

Get deliverability by domain. Deliverability broken down by recipient domain (GET /api/public/v1/motor-blocks/{id}/deliverability). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/deliverability
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive
limit	integer	No	Max recipient domains returned

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_reputation

Get sending reputation. Delivery reputation score (0 to 100) for one Motor Block, computed on request from its delivery outcomes over windowDays (the token retention window): 100 minus penalties for bounced, complained and failed recipients (GET /api/public/v1/motor-blocks/{id}/reputation). The response says what it is: kind, basis, formula and notTheSameAs. It is not the dashboard Health score (different formula and timeframe), not the internal score behind automatic throttling, and not domain health (SPF, DKIM, DMARC), so those numbers differ by design. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/reputation
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_anomalies

Get sending anomalies. Detected sending anomalies for one Motor Block — volume spikes, bounce surges, unusual patterns (GET /api/public/v1/motor-blocks/{id}/anomalies). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/anomalies
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_providers

Get outcomes by provider. Send outcomes grouped by receiving mailbox provider (GET /api/public/v1/motor-blocks/{id}/providers). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/providers
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive
limit	integer	No	Max providers returned

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_error_codes

Get SMTP error codes. SMTP error codes seen for one Motor Block, with counts and a specific diagnosis for each (GET /api/public/v1/motor-blocks/{id}/error-codes). Each row has the code, its count, a label and hint saying what it means and what to do, cause (the platform bounce bucket, for example recipient_invalid or policy_block_auth), retryable (temporary failures are retried by the platform), suggestedAction (none, retry, remove or investigate) and lookup. The stored code is basic (550), enhanced (5.7.1) or a bucket (200 delivered to a Motorical-hosted mailbox; 400 and 500 when the exact code was not recorded). Counts are the same rows motorical_get_logs returns: to see the messages behind a row, call motorical_get_logs with the row lookup (smtpCode) and read smtpResponse on one message. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/error-codes
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive
limit	integer	No	Max distinct error codes returned

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_rate_limits

Get Motor Block rate limits. Current hourly and daily send usage against this Motor Block's limits (GET /api/public/v1/motor-blocks/{id}/rate-limits). Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/rate-limits
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_account_rate_limits

Get account rate limits. Account-wide send ceiling and current usage across every Motor Block (GET /api/public/v1/account/rate-limits). Account-scoped: no Motor Block needed. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/rate-limits
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_onboarding_state

Get onboarding/account state. Where this account stands right now: stage, whether it can actually send (ready_to_send), what's blocking it, and the one next tool to call to move forward (GET /api/public/v1/account/state). Account-scoped: no Motor Block needed. Each blocker carries humanRequired (a person must act) and, where there is one, a nextAction. For an account with no plan and no domain the response also lists two onboarding options, own_domain and sandbox_domain, and a choose rule for picking between them: state the choice and the reason, and the person may override. Confirming recipients by emailed link needs the manage:recipients scope; an existing authorization must be re-approved to include it. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/state
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_whoami

Who am I (account, plan, grant). Who this connection is acting for (GET /api/public/v1/account/whoami): the account (id, owner email, name), its plan (name, status, hasSubscription) and, for an OAuth connection, the grant: the client, the scopes it holds, the Motor Blocks it covers, when it was granted, and canAdd (permissions it could still be given, with available:false where the plan does not allow it) plus addInDashboard, the page where the person adds them. Account-scoped: no Motor Block needed. grant is null when the call is not made over an OAuth grant. Over OAuth it needs no scope, so any connection can ask what it holds, and every server lists it. Use it instead of inferring scopes from the tool list.

Property	Value
Needs scope	No scope: any OAuth connection can call it
Available on	Hosted servers: main, transactional, analytics, domains, sandbox, webhooks, motorBlocks; the local server too
Acts on	The whole account (no Motor Block needed)
REST route	GET /api/public/v1/account/whoami
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Optional. This operation acts on the whole account, so a Motor Block is never needed; pass one only to record which block the call was made on behalf of.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_logs

Search send logs. Search send logs for one Motor Block (GET /api/public/v1/motor-blocks/{id}/logs). Paginate with cursor. Recipient addresses are masked unless the token carries logs.pii, which OAuth tokens never do. To find failures by cause use smtpCode: the stored code is whatever the receiving server reported, in either form (basic like 550 or enhanced like 5.7.1), so a class such as 5xx (all permanent failures), 4xx (all temporary ones) or a group such as 5.7.x (policy and reputation blocks) is usually what you want; an exact code matches only that exact form. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/logs
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
from	string	No	ISO date or datetime, inclusive
to	string	No	ISO date or datetime, inclusive
currentOutcome	string	No	Filter to one delivery outcome, e.g. delivered, bounced, deferred
smtpCode	string	No	Filter by SMTP code, as the receiving server reported it (basic like 550 or enhanced like 5.7.1, both appear in the same logs). Forms: exact 550 or 5.7.1; a class 5xx or 4xx (5.x.x also works); a group 5.7.x; or a comma-separated list of up to 10, no spaces, e.g. 5.7.x,4xx. An invalid value is a 400 that says what is accepted
query	string	No	Space-separated key:value terms, all of which must match: recipient:<exact address>, domain:<exact domain>, code:<an SMTP code filter in the same forms as smtpCode, no spaces>, id:<message uuid>. Text without a key: prefix is ignored; there is no subject search.
limit	integer	No	Page size
cursor	string	No	Opaque cursor from a previous page
includePII	boolean	No	Unmask recipient addresses. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_message_by_smtp_id

Get message by SMTP Message-ID. Look up one message by its SMTP Message-ID header (GET /api/public/v1/messages?smtpMessageId=). This is a lookup, not a listing: an exact id is required and at most one message is returned. Use motorical_get_message when you have the internal send UUID instead. Requires OAuth scope: read:analytics (Read delivery logs, analytics, and usage for the caller's Motor Block(s). Never includes unmasked recipient PII (logs.pii) regardless of what is requested.).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/messages
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
smtpMessageId	string	Yes	The exact SMTP Message-ID, angle brackets included
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
includePII	boolean	No	Unmask the recipient address. Requires the logs.pii scope, which is never granted to OAuth tokens — the API returns 403.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"smtpMessageId":"<smtpMessageId>"}

motorical_get_config

Get Motor Block config. Configuration of one Motor Block — its sending domain, limits, delivery settings, and activeAuthMethod ("Password"/"API Key"/"OAuth 2.0"/"mTLS", read-only -- changing it is dashboard-only) (GET /api/public/v1/motor-blocks/{id}/config). Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/config
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_get_domain_health

Get domain health. DNS and email-authentication health for the Motor Block's sending domain — SPF, DKIM, DMARC, MX (GET /api/public/v1/motor-blocks/{id}/domain-health). This is a set-up status, not a score, and it is separate from the delivery reputation score (motorical_get_reputation), which measures delivery outcomes. Requires OAuth scope: read:domains (List and read sending domains, their DNS records and email-authentication health, and read a Motor Block's configuration, without adding or verifying any domain.).

Property	Value
Needs scope	read:domains
Available on	Hosted servers: main, domains; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/domain-health
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
refresh	boolean	No	Re-run the live DNS checks now instead of returning the last cached result

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_webhook_list

List webhook endpoints. List webhook endpoints registered on one Motor Block (GET /api/public/v1/motor-blocks/{id}/webhooks). Requires OAuth scope: read:webhooks (List webhook endpoints and read their delivery history and stats, without creating, updating, deleting, or testing any.).

Property	Value
Needs scope	read:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/webhooks
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{}

motorical_webhook_create

Create webhook endpoint. Register a new webhook endpoint on one Motor Block (POST /api/public/v1/motor-blocks/{id}/webhooks). The response includes the full signing secret exactly once — store it immediately, it is only masked on every later read. Requires OAuth scope: manage:webhooks (Create, update, delete, and test webhook endpoints on the caller's Motor Block(s). Includes everything read:webhooks grants.).

Property	Value
Needs scope	manage:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /api/public/v1/motor-blocks/{id}/webhooks
Behaviour	Changes data

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
url	string	Yes	HTTPS endpoint that will receive webhook deliveries
events	array of string	No	Event types to subscribe to; defaults to all event types when omitted
idempotencyKey	string	No	Optional. Pass the same value on a retry to get the exact original response back, instead of a duplicate.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"url":"<url>"}

motorical_webhook_update

Update webhook endpoint. Update a webhook endpoint's url, events, or enabled state (PUT /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}). Only the fields you pass are changed. Requires OAuth scope: manage:webhooks (Create, update, delete, and test webhook endpoints on the caller's Motor Block(s). Includes everything read:webhooks grants.).

Property	Value
Needs scope	manage:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	PUT /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}
Behaviour	Changes data; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
webhookId	string	Yes	The webhook endpoint id, from motorical_webhook_list or the create response
url	string	No	-
events	array of string	No	-
enabled	boolean	No	-
idempotencyKey	string	No	Optional. Pass the same value on a retry to get the exact original response back, instead of a duplicate.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"webhookId":"<webhookId>"}

motorical_webhook_delete

Delete webhook endpoint. Delete a webhook endpoint (DELETE /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}). Requires OAuth scope: manage:webhooks (Create, update, delete, and test webhook endpoints on the caller's Motor Block(s). Includes everything read:webhooks grants.).

Property	Value
Needs scope	manage:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	DELETE /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}
Behaviour	Destructive: asks the person to confirm; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
webhookId	string	Yes	The webhook endpoint id, from motorical_webhook_list or the create response
confirm	boolean	No	Required: true. Confirms this destructive action.

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"webhookId":"<webhookId>"}

motorical_webhook_test

Send test webhook delivery. Send a synthetic test delivery to a webhook endpoint (POST /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/test). Requires OAuth scope: manage:webhooks (Create, update, delete, and test webhook endpoints on the caller's Motor Block(s). Includes everything read:webhooks grants.).

Property	Value
Needs scope	manage:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	POST /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/test
Behaviour	Changes data

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
webhookId	string	Yes	The webhook endpoint id, from motorical_webhook_list or the create response

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"webhookId":"<webhookId>"}

motorical_webhook_get_deliveries

Get webhook delivery attempts. Recent delivery attempts for one webhook endpoint (GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/deliveries). Requires OAuth scope: read:webhooks (List webhook endpoints and read their delivery history and stats, without creating, updating, deleting, or testing any.).

Property	Value
Needs scope	read:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/deliveries
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
webhookId	string	Yes	The webhook endpoint id, from motorical_webhook_list or the create response
limit	integer	No	Default 50, max 200

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"webhookId":"<webhookId>"}

motorical_webhook_get_stats

Get webhook delivery stats. Delivery success/failure counts and average latency for one webhook endpoint over a time window (GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/stats). Requires OAuth scope: read:webhooks (List webhook endpoints and read their delivery history and stats, without creating, updating, deleting, or testing any.).

Property	Value
Needs scope	read:webhooks
Available on	Hosted servers: main, webhooks; the local server too
Acts on	One Motor Block (the motorBlockId input)
REST route	GET /api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/stats
Behaviour	Read-only; safe to repeat

Input	Type	Required	Meaning
motorBlockId	string (uuid)	No	Required when the authorization covers more than one Motor Block
webhookId	string	Yes	The webhook endpoint id, from motorical_webhook_list or the create response
hours	integer	No	Default 24, max 168 (7 days)

Returns the JSON of the REST route above.

Example arguments (placeholders in angle brackets, required inputs only):

{"webhookId":"<webhookId>"}

motorical_integrate_send

MCP prompt, not a callable tool. Guidance for integrating Motorical transactional email (HTTP Send) safely. It takes one optional language argument (for example node, python, curl).

Property	Value
Needs scope	send:transactional
Available on	Hosted servers: main, transactional; the local server too