Connect and send your first email

What you are looking at: the shortest path to your first sent email over HTTPS (POST /v1/send). You will get a Motor Block API key, check a message without sending it, send it, and look it up. If you prefer SMTP, the SMTP quickstart uses the same Motor Block.

You need a verified sending domain attached to a Motor Block. The dashboard walks you through creating both.

1. Get your Motor Block API key

1. In the dashboard open Motor Blocks and open your block's SMTP configuration.
2. Choose the API key authentication method.
3. Select New API Key and copy the mk_live_… value immediately: it is shown once, and creating a new key makes the previous key stop working.

2. Put it in your shell

export MK_API_KEY="mk_live_YOUR_KEY"

3. Check the message without sending it

curl -X POST "https://api.motorical.com/v1/send" \
  -H "Authorization: ApiKey $MK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "fromName": "Acme Billing",
    "to": ["recipient@example.com"],
    "subject": "Dry run check",
    "text": "Validate this email without sending it.",
    "dryRun": true
  }'

You should see "success": true and "status": "validated". Use a from address on your verified domain.

4. Send it

Remove dryRun (or set it to false):

curl -X POST "https://api.motorical.com/v1/send" \
  -H "Authorization: ApiKey $MK_API_KEY" \
  -H "Idempotency-Key: first-email-1" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "fromName": "Acme Billing",
    "to": ["recipient@example.com"],
    "subject": "My first Motorical email",
    "text": "It works."
  }'

A successful send returns data.id and "acceptanceStatus": "queued". Keep data.id.

5. Prove it was delivered

Looking a message up uses a Public API token, not the send key. Follow Connect to the API steps 1 to 4, asking for the logs.read scope in step 4, then:

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

Everything you can put in the request

These are all the fields of POST /v1/send, generated from the API definition so this list cannot fall behind it:

Field	Type	Required	Meaning
from	string	Yes	Sender address (must match motor block domain). Bare email only — use fromName for display name.
fromName	string	No	Optional From display name (e.g. "Acme Billing"). Produces From: "Acme Billing" addr@domain. Do not set a From custom header (DISALLOWED_HEADERS).
to	string or array of string	Yes	Recipient address, or a list of addresses. One request is one message: every recipient receives the same message and the To header shows the addresses as written. For a separate message per person, send one request each.
cc	string or array of string	No	Copy recipients, named in the Cc header. to, cc and bcc together take at most 50 addresses. Rolling out per Motor Block: 422 feature_not_enabled where not available.
bcc	string or array of string	No	Blind-copy recipients: they receive the message but are named in no header. Rolling out per Motor Block.
replyTo	string	No	Reply-To address. Not allowed together with a Reply-To custom header (422 conflicting_fields). Rolling out per Motor Block.
subject	string	Yes	Email subject
text	string	No	Plain text body
html	string	No	HTML body
headers	object	No	Custom headers applied to the outgoing message and DKIM-signed (e.g. In-Reply-To, References, Reply-To, List-Unsubscribe, custom X-). Reserved/spoofable headers are rejected with 400 DISALLOWED_HEADERS: From, Sender, Return-Path, To, Cc, Bcc, Subject, Date, Message-ID, MIME-Version, Content-, DKIM-Signature, Received, Authentication-Results, ARC-, X-Motorical-. Header values containing CR/LF are also rejected.
attachments	array of object	No	Files to attach. Your plan decides how many, how large (per file and in total) and which types, exactly as over SMTP; a refusal names the plan and the limit. Rolling out per Motor Block: 422 feature_not_enabled where not available.
dryRun	boolean	No	Validate without queueing or writing email logs. With attachments it also runs the plan check (not the virus and content scan).
Idempotency-Key (header)	string	No	Unique key to prevent duplicate sends (24h window)

An array in to is one message sent to every recipient, who can see each other; for a separate message per person send one request each. cc, bcc and replyTo are rolling out per Motor Block: A Motor Block that has not been moved to the new sending path answers 422 with code feature_not_enabled and sends nothing (the fields are never silently dropped), so use SMTP there. headers adds your own headers (such as In-Reply-To, References or List-Unsubscribe); reserved ones are refused, see Custom headers. All of them together, checked with dryRun:

curl -X POST "https://api.motorical.com/v1/send" \
  -H "Authorization: ApiKey $MK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "billing@yourdomain.com",
    "fromName": "Acme Billing",
    "to": ["customer@example.com"],
    "cc": ["accounts@example.com"],
    "bcc": "archive@yourdomain.com",
    "replyTo": "support@yourdomain.com",
    "subject": "Your invoice",
    "text": "Your invoice is ready.",
    "headers": { "List-Unsubscribe": "<mailto:unsubscribe@yourdomain.com>" },
    "dryRun": true
  }'

Where to go next

• Transactional Email API (HTTP Send): every field, attachments, cc/bcc, errors.
• Rate limits: what happens when you send too fast.
• Troubleshooting SMTP.

All HTTP send calls

These 3 calls are generated from the API definition at build time. Type in the box to filter.

Method	Endpoint	What it does
POST	/v1/send	Send or validate an email
GET	/v1/status	Get HTTP Send API service status
POST	/v1/test-email	Test SMTP setup parameters