MCP tools: Analytics

Reading delivery results, reputation and limits. This page is the slice of the full MCP tool reference for the analytics server (the other servers are listed on the hosted servers page). The main server carries every tool, so these entries apply there too. Failures use the shape described in MCP errors.

motorical_list_motor_blocks

List Motor Blocks. List the Motor Blocks (isolated sending streams) this connection covers: id and name only, of every type, active or not (so marketing and companion blocks appear too). Use it to find a valid motorBlockId. For type, domain, status and management use motorical_motor_block_list (production blocks only); for the account-wide picture including inactive blocks use motorical_get_onboarding_state. Auto-mints a Public API token with ak_live_ on the local server if needed. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

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)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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_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. Rates are percentages of finalized recipients (accepted = delivered + processed + complained, plus bounced and failed); "processed" means the receiving server accepted the message, and queued or deferred recipients are counted as pending, not in the rates. totals.accepted, finalized and pending and rates.basis spell this out; generatedAt says when the figures were computed. Its reputation block is the same delivery reputation score as motorical_get_reputation. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. Rates use the same finalized-recipient definition as motorical_get_overview (rateBasis says so); days with no sends are not returned. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. 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 (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. deliveryRate uses the same finalized-recipient definition as motorical_get_overview (accepted includes processed; rateBasis says so). Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. 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 accepted with the exact reply not recorded, which includes delivery 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 (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. Requires OAuth scope: read:analytics (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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 (see motorical_whoami for what it allows).

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)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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_whoami

Who am I (account, plan, grant). Who this connection is acting for: the account (id, owner email, name), its plan (name, status, hasSubscription), account.billing (price amount in minor units + currency + interval, trial end, current period end / next renewal date, cancelAtPeriodEnd and endsAt, this month's sends against the plan cap, and paymentMethod.status ok or failing; never invoices, receipts or card details; a field it cannot resolve is null with its reason under billing.unavailable) 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, communications; the local server too
Acts on	The whole account (no Motor Block needed)
Not listed	Never
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. 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 (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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. 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 (see motorical_whoami for what it allows).

Property	Value
Needs scope	read:analytics
Available on	Hosted servers: main, analytics; the local server too
Acts on	One Motor Block (the motorBlockId input)
Not listed	When the connection does not hold the scope (the narrow servers hide it; the main server lists it marked "Needs permission")
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>"}