Skip to main content

API Endpoints

All endpoints are relative to the base URL:

https://api.motorical.com/api/public/v1

For interactive testing, use the Swagger UI.

Motor Blocks​

GET /motor-blocks​

Lists all motor blocks you have access to. Use this first to discover your block IDs.

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks"

Response: Array of motor blocks with names, IDs, and basic info.

GET /motor-blocks/{id}/overview​

One-call overview with totals, rates, reputation, rate limits, anomalies, and top domains.

Scopes: analytics.read, usage.read

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/overview"

Ideal for dashboards, health checks, and monitoring UIs that need a compact summary.

GET /motor-blocks/{id}/daily-summary​

Daily rollups over a recent window (sent, delivered, bounced, complained + rates).

Parameters:

ParameterDescription
daysNumber of days to include (up to your retention window)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/daily-summary?days=30"

GET /motor-blocks/{id}/rate-limits​

Current usage vs your plan limits.

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/rate-limits"

Response: Current usage counts, limits, and reset times for burst/hour/day periods.

GET /motor-blocks/{id}/metrics​

Email performance data (sent, delivered, bounced, complained) with time-series breakdowns.

Parameters:

ParameterDescription
intervalhour or day (required)
fromStart time (ISO 8601)
toEnd time (ISO 8601)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/metrics?interval=hour&from=2024-01-15T00:00:00Z&to=2024-01-16T00:00:00Z"

GET /motor-blocks/{id}/logs​

Search individual email events and records.

Parameters:

ParameterDescription
querySearch filter (see query syntax below)
statussent, delivered, bounced, complained, deferred, failed
fromStart time (ISO 8601)
toEnd time (ISO 8601)
limitMax results (1–1000, default 100)
cursorFor pagination (use nextCursor from response)

Query Syntax:

  • recipient:[email protected] — specific email address
  • domain:gmail.com — all emails to Gmail
  • status:bounced — only bounced emails
  • metadata.campaign_id:newsletter-2024 — by campaign metadata
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/logs?query=domain:gmail.com&status=bounced&limit=50"

GET /motor-blocks/{id}/providers​

Aggregate performance by mailbox provider (gmail, outlook, yahoo, other).

Parameters:

ParameterDescription
fromStart time (ISO 8601)
toEnd time (ISO 8601)
limitMax providers to return (default 20)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/providers?from=2024-01-01T00:00:00Z&to=2024-01-08T00:00:00Z"

GET /motor-blocks/{id}/error-codes​

Summarize SMTP response codes with human-friendly categories and hints.

Parameters: from, to, limit (default 50)

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/error-codes?from=2024-01-01T00:00:00Z&to=2024-01-08T00:00:00Z"

GET /motor-blocks/{id}/config​

Read-only snapshot of a motor block's non-sensitive configuration and domain status.

Scopes: config.read

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/config"

GET /motor-blocks/{id}/domain-health​

Summarized SPF/DKIM/DMARC and verification status for the attached domain.

Scopes: config.read

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/domain-health"

Messages​

GET /messages/{messageId}/timeline​

Synthetic lifecycle view for a single message (queued → final result).

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/messages/$MESSAGE_ID/timeline"

Use the messageId from your own logs or from /logs responses.

Webhooks​

GET /motor-blocks/{id}/webhooks/{webhookId}/stats​

High-level stats for webhook delivery (delivered, failed, queued, failure rate, latency).

Scopes: webhooks.manage

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/webhooks/$WEBHOOK_ID/stats?hours=24"

Exports​

GET /motor-blocks/{id}/exports/preview​

Lightweight preview of recent logs without creating a background export job.

Parameters:

ParameterDescription
limitMax records to return (default 100, max 500)
includePIItrue/false (requires logs.pii scope for unmasked recipients)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/exports/preview?limit=100"

Events (Server-Sent Events)​

GET /motor-blocks/{id}/events/stream​

Real-time event stream of email delivery events.

curl -N -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/events/stream"

Events are delivered as SSE with types: ready, keepalive, and message.