Transactional Email API (HTTP Send)

Use Motorical's transactional email API (POST /v1/send) when your application wants to send email over HTTPS instead of SMTP. Authenticate with a Motor Block API key. Start with dryRun: true to validate the same payload without queueing an email.

What You Need

Verified domainYour from address must use the domain attached to the Motorical SMTP Motor Block.

Motorical SMTP Motor Block API KeyUse a full mk_live_... key, not an Account API Key.

Sender addressUse a real, monitored address such as info@yourdomain.com. Optional fromName sets the inbox display name (do not put a display name in from or a From header).

:::tip Key distinction POST /v1/send uses a Motorical SMTP Motor Block API Key: Authorization: ApiKey mk_live_....

Do not use a Public API bearer token or an Account API Key for sending. :::

1. Dry-Run the Payload

Dry run validates authentication, sender domain, DNS readiness, recipient shape, subject, and body size. It does not create an email log or queue delivery work.

curl

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.",
    "html": "<p>Validate this email without sending it.</p>",
    "dryRun": true
  }'

Node.js

const response = await fetch('https://api.motorical.com/v1/send', {
  method: 'POST',
  headers: {
    Authorization: `ApiKey ${process.env.MK_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'sender@yourdomain.com',
    fromName: 'Acme Billing',
    to: ['recipient@example.com'],
    subject: 'Dry run check',
    text: 'Validate this email without sending it.',
    html: '<p>Validate this email without sending it.</p>',
    dryRun: true
  })
});

console.log(await response.json());

Python

import os
import requests

response = requests.post(
    "https://api.motorical.com/v1/send",
    headers={
        "Authorization": f"ApiKey {os.environ['MK_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "from": "sender@yourdomain.com",
        "fromName": "Acme Billing",
        "to": ["recipient@example.com"],
        "subject": "Dry run check",
        "text": "Validate this email without sending it.",
        "html": "<p>Validate this email without sending it.</p>",
        "dryRun": True,
    },
    timeout=30,
)

print(response.json())

PHP

<?php
$payload = [
    "from" => "sender@yourdomain.com",
    "fromName" => "Acme Billing",
    "to" => ["recipient@example.com"],
    "subject" => "Dry run check",
    "text" => "Validate this email without sending it.",
    "html" => "<p>Validate this email without sending it.</p>",
    "dryRun" => true,
];

$ch = curl_init("https://api.motorical.com/v1/send");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: ApiKey " . getenv("MK_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

echo curl_exec($ch);
curl_close($ch);

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

func main() {
	payload := map[string]any{
		"from":     "sender@yourdomain.com",
		"fromName": "Acme Billing",
		"to":       []string{"recipient@example.com"},
		"subject":  "Dry run check",
		"text":     "Validate this email without sending it.",
		"html":     "<p>Validate this email without sending it.</p>",
		"dryRun":   true,
	}

	body, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", "https://api.motorical.com/v1/send", bytes.NewReader(body))
	req.Header.Set("Authorization", "ApiKey "+os.Getenv("MK_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	fmt.Println(resp.Status)
}

Expected dry-run response:

{
  "success": true,
  "dryRun": true,
  "data": {
    "status": "validated",
    "from": "sender@yourdomain.com",
    "fromName": "Acme Billing",
    "domain": "yourdomain.com",
    "recipientCount": 1,
    "bodySize": 42
  }
}

2. Send the Email

Remove dryRun or set it to false. Add an Idempotency-Key header if your application may retry the request.

curl -X POST "https://api.motorical.com/v1/send" \
  -H "Authorization: ApiKey $MK_API_KEY" \
  -H "Idempotency-Key: order-12345-welcome-email" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "sender@yourdomain.com",
    "fromName": "Acme Billing",
    "to": ["recipient@example.com"],
    "subject": "Welcome to our app",
    "text": "Thanks for signing up.",
    "html": "<p>Thanks for signing up.</p>"
  }'

Successful sends return a messageId and status: "queued".

3. Check Delivery

Use the Public API to inspect logs and timeline events. These endpoints use a short-lived bearer token minted with an Account API Key.

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.motorical.com/api/public/v1/messages/$MESSAGE_ID/events"

For real-time automation, create a webhook for message.delivered, message.bounced, and message.complained.

Common Errors

Error	What it means	Fix
401 Invalid API key format	The key is missing, truncated, or the wrong type.	Use a full mk_live_... Motorical SMTP Motor Block API Key.
403 From address domain does not match	Sender domain is not attached to the Motorical SMTP Motor Block.	Send from the verified SMTP Motor Block domain.
403 Domain DNS setup incomplete	SPF or DKIM is not ready.	Complete domain DNS setup before sending.
422 Validation error	Required fields or body content are missing.	Include from, to, subject, and at least one of text or html.

Related Reference

• Motorical SMTP GitHub examples
• Node HTTP Send example
• Python HTTP Send example
• API authentication
• Full endpoint reference
• Webhook management