Connect to the API

What you are looking at: the shortest path from "I have a Motorical account" to "my first API call worked, and I can prove it". Follow the steps in order, copy each command, and when step 5 shows your account you are connected. The table at the bottom lists every API call in this reference, so you can then jump to the one you need.

This page covers the Public API (logs, analytics, domains, webhooks, exports and account state). To send email see Send Email: connect; for campaigns see Marketing Communications Block: connect.

1. Create an Account API key

1. In the Motorical dashboard open Settings → API Access.
2. Open the Account API Keys section and choose Create API Key.
3. Copy the full key when it is shown. It looks like ak_live_…. A masked value in the list is not usable for API calls.

2. Find your Motor Block ID

Still on Settings → API Access, select your Motor Block in the selector. The page shows its Motor Block ID with a copy button.

3. Put both values in your shell

export AK_API_KEY="ak_live_YOUR_KEY"
export MOTOR_BLOCK_ID="YOUR_MOTOR_BLOCK_ID"

Keep the key out of source code, screenshots and support messages.

4. Exchange the key for a short-lived token

The Public API takes a short-lived bearer token. This command mints one and stores it:

export MOTORICAL_TOKEN=$(curl -sS -X POST https://api.motorical.com/api/public/token/account-key \
  -H "Authorization: ApiKey $AK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"motorBlockId\": \"$MOTOR_BLOCK_ID\", \"scopes\": [\"config.read\"], \"ttlSeconds\": 300}" \
  | jq -r .data.token)

The token expires after ttlSeconds; run the command again when it does.

5. Prove it works

curl -sS https://api.motorical.com/api/public/v1/account/whoami \
  -H "Authorization: Bearer $MOTORICAL_TOKEN" | jq .

You are connected when the response has "success": true and shows your account and plan.

If it does not work

You see	Meaning	What to do
401 on step 4	The key is wrong, masked, or not an Account API key	Create a new Account API key and copy the whole value. A mk_live_… Motor Block key does not work here.
404 Motor block not found	The ID does not belong to this account	Copy the ID again from Settings → API Access.
No valid scopes requested	Your key was created without the permission you asked for	Create a key that includes it, or ask for a narrower scope.
401 on step 5	The token expired or was not stored	Run step 4 again and check echo $MOTORICAL_TOKEN is not empty.

6. Move on to the calls you need

• Authentication: every credential type and scope, and when to use which.
• Endpoints: request and response details.
• Rate limits and Webhooks.

All API calls

These 74 calls are generated from the API definition each time the documentation is built, so the list cannot drift from the API. Type in the box to filter by method, path or description.

Method	Endpoint	What it does	Scope
POST	/api/auth/login	Password login (returns JWT + refreshToken)	—
POST	/api/auth/refresh	Rotate refresh token; issue new access JWT (non-interactive)	—
POST	/api/auth/register	Start agent signup (email verification code)	—
POST	/api/auth/set-password	Set password after email verification (returns JWT + refreshToken)	—
POST	/api/auth/verify-code	Verify email with 6-digit code	—
POST	/api/auth/web-handoff	Mint a one-time browser handoff URL	—
GET	/api/developer/sandbox	Get developer sandbox status	—
POST	/api/developer/sandbox/convert	Convert sandbox Motor Block to a verified production domain	—
PATCH	/api/developer/sandbox/outbound	Update sandbox outbound lock / allowlist	—
POST	/api/developer/sandbox/provision	Provision unpaid developer sandbox	—
POST	/api/domains	Add a customer domain	—
POST	/api/domains/{id}/check-dns	Check DKIM/SPF/DMARC and persist send-readiness flags	—
POST	/api/domains/{id}/verify	Verify ownership and refresh DKIM/SPF send-readiness	—
GET	/api/oauth2/authorize	OAuth 2.0 authorization endpoint (consent HTML)	—
POST	/api/oauth2/token	OAuth 2.0 token endpoint	—
GET	/api/oauth2/validate	Validate an OAuth access token	—
POST	/api/public/token	Mint a Public Analytics API token with a dashboard JWT	—
POST	/api/public/token/account-key	Mint a Public Analytics API token with an Account API Key	—
GET	/api/public/v1/account/authorization/motor-blocks/{id}	Live grant-coverage check for one Motor Block (infrastructure)	—
GET	/api/public/v1/account/free-recipients	List Free-account recipients (OAuth/Public API bearer)	—
POST	/api/public/v1/account/free-recipients	Ask a recipient to allow test email (OAuth/Public API bearer)	—
DELETE	/api/public/v1/account/free-recipients/{id}	Remove a Free-account recipient (OAuth/Public API bearer)	—
GET	/api/public/v1/account/motor-block-deletions/{jobId}	Poll a permanent-deletion job	—
GET	/api/public/v1/account/motor-blocks	List the account's production Motor Blocks (OAuth/Public API bearer)	—
POST	/api/public/v1/account/motor-blocks	Create a production Motor Block (OAuth/Public API bearer)	—
DELETE	/api/public/v1/account/motor-blocks/{id}	Permanently delete a Motor Block — asynchronous and irrecoverable	—
POST	/api/public/v1/account/motor-blocks/{id}/assign-domain	Assign a verified domain to a Motor Block	—
POST	/api/public/v1/account/motor-blocks/{id}/deactivate	Deactivate (pause) a Motor Block — reversible	—
PATCH	/api/public/v1/account/motor-blocks/{id}/name	Rename a Motor Block (display name only)	—
POST	/api/public/v1/account/motor-blocks/{id}/reactivate	Reactivate a deactivated Motor Block	—
PATCH	/api/public/v1/account/motor-blocks/{id}/type	Switch a Motor Block between transactional and general_purpose	—
GET	/api/public/v1/account/rate-limits	Account-wide rate limits	usage.read
GET	/api/public/v1/account/sandbox	Get account sandbox status (OAuth/Public API bearer)	—
POST	/api/public/v1/account/sandbox/convert	Convert account sandbox to a verified production domain (OAuth/Public API bearer)	—
POST	/api/public/v1/account/sandbox/provision	Provision account sandbox (OAuth/Public API bearer)	—
GET	/api/public/v1/account/state	Composed account state	config.read
GET	/api/public/v1/account/whoami	Account identity, plan and grant	config.read
GET	/api/public/v1/domains	List domains on the account	config.read
POST	/api/public/v1/domains	Add a customer domain (account-wide, OAuth/MCP-capable)	config.manage
GET	/api/public/v1/domains/{id}	One sending domain	config.read
POST	/api/public/v1/domains/{id}/check-dns	Check DKIM/SPF/DMARC and persist send-readiness flags (account-wide, OAuth/MCP-capable)	config.manage
GET	/api/public/v1/domains/{id}/dns-records	DNS records to publish for one domain	config.read
GET	/api/public/v1/domains/{id}/health	Email-authentication health of one domain	config.read
POST	/api/public/v1/domains/{id}/verify	Verify ownership and refresh DKIM/SPF send-readiness (account-wide, OAuth/MCP-capable)	config.manage
GET	/api/public/v1/exports/{jobId}	Get export job status	analytics.read
GET	/api/public/v1/exports/{jobId}/download	Download export file (signed token, single-use)	—
GET	/api/public/v1/messages	Lookup message by RFC Message-ID header	logs.read
GET	/api/public/v1/messages/{id}	Get message by send id (UUID)	logs.read
GET	/api/public/v1/messages/{id}/events	Get message event timeline	logs.read
GET	/api/public/v1/messages/{id}/recipients	Per-recipient outcomes for a multi-recipient send	logs.read
GET	/api/public/v1/motor-blocks	List motor blocks bound to the token	logs.read
GET	/api/public/v1/motor-blocks/{id}/anomalies	Anomaly detection (bounce spikes)	analytics.read
GET	/api/public/v1/motor-blocks/{id}/config	Motor Block config snapshot	config.read
GET	/api/public/v1/motor-blocks/{id}/daily-summary	Daily summary	analytics.read
GET	/api/public/v1/motor-blocks/{id}/deliverability	Deliverability by recipient domain	analytics.read
GET	/api/public/v1/motor-blocks/{id}/domain-health	Domain health (SPF/DKIM/DMARC): a set-up status, not a score	config.read
GET	/api/public/v1/motor-blocks/{id}/error-codes	SMTP error code diagnostics	analytics.read
GET	/api/public/v1/motor-blocks/{id}/events/stream	Event stream (SSE)	logs.read
GET	/api/public/v1/motor-blocks/{id}/exports	List recent export jobs	analytics.read
POST	/api/public/v1/motor-blocks/{id}/exports	Create export job	analytics.read
GET	/api/public/v1/motor-blocks/{id}/exports/preview	Preview recent logs (no job creation)	analytics.read, logs.read
GET	/api/public/v1/motor-blocks/{id}/logs	Search logs with cursor pagination	logs.read
GET	/api/public/v1/motor-blocks/{id}/metrics	Metrics series and totals	analytics.read
GET	/api/public/v1/motor-blocks/{id}/overview	Motor Block overview	analytics.read, usage.read
GET	/api/public/v1/motor-blocks/{id}/providers	Provider breakdown (gmail, outlook, yahoo, other)	analytics.read
GET	/api/public/v1/motor-blocks/{id}/rate-limits	Motor Block rate limits	usage.read
GET	/api/public/v1/motor-blocks/{id}/reputation	Delivery reputation score	analytics.read
GET	/api/public/v1/motor-blocks/{id}/webhooks	List webhooks	webhooks.read
POST	/api/public/v1/motor-blocks/{id}/webhooks	Create webhook	webhooks.manage
PUT	/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}	Update webhook	webhooks.manage
DELETE	/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}	Delete webhook	webhooks.manage
GET	/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/deliveries	Webhook delivery history	webhooks.read
GET	/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/stats	Webhook delivery stats	webhooks.read
POST	/api/public/v1/motor-blocks/{id}/webhooks/{webhookId}/test	Enqueue a test webhook delivery	webhooks.manage