Data Exports

Export email logs, metrics, and analytics data from Motorical.

Quick Preview

Get a lightweight preview of recent logs without creating a background job:

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/motor-blocks/$BLOCK_ID/exports/preview?limit=100"

Parameters:

Parameter	Description
limit	Max records (default 100, max 500)
includePII	true/false (requires logs.pii scope)

Background Export Jobs

For larger exports, create a background job that generates an NDJSON download:

Create an Export Job

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jobType":"logs"}' \
  "$BASE_URL/motor-blocks/$BLOCK_ID/exports"

Parameters:

Parameter	Description
jobType	logs or metrics (default logs)
includePII	true/false (requires logs.pii scope). Default false — the generated file has recipient addresses masked, same as the preview endpoint.

Returns 202 Accepted with the job id and status: "queued".

List Export Jobs

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

Returns the 50 most recent export jobs with id, status, job_type, and created_at.

Check Job Status

curl -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/exports/$JOB_ID"

When the job is complete, the response includes a download_url with a short-lived (15-minute) download token.

Download Export

curl -o export.ndjson \
  "$BASE_URL/exports/$JOB_ID/download?token=$DOWNLOAD_TOKEN"

Downloads the completed export as an NDJSON file. The download token is single-use and expires after 15 minutes — a successful download deletes the file immediately, so a second request with the same token 404s. If the download didn't complete (dropped connection, etc.), poll job status again for a fresh token against the same file. Exports are not retained: an unretrieved file is deleted automatically 24 hours after the job completes, whether or not it was ever downloaded.

Export Formats

Format	Use Case
NDJSON	Machine-readable, streaming-friendly
CSV	Available for Communications Block contact exports
JSON	GDPR data portability exports

Communications Block Exports

Contact List Export

Download complete contact lists:

GET /comm-api/api/lists/{id}/contacts/export
X-Tenant-Id: your-tenant-uuid

GDPR Data Export

Comprehensive per-contact data export including profile, campaign history, tracking events, and suppression status. Delivered via email as JSON and CSV attachments.

Best Practices

• Use preview exports for quick debugging
• Schedule background exports for large datasets
• Download promptly — files are not retained past a single download or 24 hours, whichever comes first
• Only request includePII: true when you actually need unmasked recipient data, and store what you download securely
• Monitor export job status via the API