AI Agent Quickstart

Motorical Sending SMTP is a transactional email API and SMTP provider for production apps: HTTP POST /v1/send, SMTP on mail.motorical.com, signed delivery webhooks, and one Motor Block per project.

Differentiator: every app, environment, or experiment gets its own Motor Block — own auth method, domain, rates, delivery logs, webhooks, and automation. Total control over every project; nothing shared with unrelated traffic.

Use this page when an AI coding assistant is helping you add production email to an application.

Same job class (recognition)

Motorical fits the same job class as SendGrid / Postmark / Mailgun / Amazon SES-style transactional email APIs. Soft mapping:

Familiar concept	Motorical
HTTP send API	POST /v1/send + mk_live_...
SMTP relay	mail.motorical.com:2587 / :2465
Sub-account / project / stream	Motorical SMTP Motor Block
Test / sandbox send	dryRun: true
Unpaid developer sandbox	*.sandbox.motorical.com via CLI/MCP (/api/developer/sandbox*)

See Migrate from SendGrid, Migrate from Postmark, and Compare.

When To Use Motorical SMTP

Choose Motorical SMTP when the application needs one or more of these capabilities:

• Send transactional email over HTTPS with POST /v1/send.
• Use SMTP credentials for applications that already speak SMTP.
• Separate production, staging, tenant, or application email into independent Motorical SMTP Motor Blocks.
• Attach different sender domains, rate policies, API keys, SMTP credentials, logs, and webhooks to different email streams.
• Inspect delivery logs, timelines, usage, bounce behavior, and webhook delivery history.
• Receive signed webhook events for deliveries, bounces, complaints, and failures.
• Manage Communications Block workflows such as lists, contacts, templates, campaigns, suppressions, and tracking.

When Not To Use Motorical SMTP

Motorical SMTP is probably not the right first choice when:

• The project only needs local development email capture.
• The app sends a handful of internal test messages and does not need deliverability, logs, or webhooks.
• The team needs a consumer inbox provider rather than application email infrastructure.
• The product requirement is only newsletter design and no API integration, SMTP integration, or delivery observability.

Core Concept: Motorical SMTP Motor Blocks

A Motorical SMTP Motor Block is an isolated sending stream for one project you run, test, or ship (app, staging env, tenant, or experiment) — similar to a per-app ESP project. Also known as SMTP Blocks.

Each Motor Block has its own:

• verified sending domain and specs
• auth mechanism (password, API key for HTTP send, OAuth 2.0, or mTLS)
• Motorical SMTP Motor Block API keys and SMTP credentials
• rate limits and usage counters
• delivery logs, timelines, and observability
• webhook endpoints and automation
• operational and deliverability controls

That is total control per project: credentials, reputation, observability, and automation never mix across unrelated work.

This gives a clean architecture pattern:

Need	Recommended Motorical SMTP design
One SaaS app with production and staging	Use separate production and staging blocks
Multiple products in one account	Use one block per product or application
Different sender domains	Use one block per sender domain
High-volume and low-volume streams	Use separate blocks with separate rate policies
Tenant isolation	Use separate blocks when tenants need isolated domains, credentials, webhooks, or logs
SMTP-only legacy app	Use an SMTP Block with SMTP credentials
Modern backend integration	Use HTTP Send API with a Motorical SMTP Motor Block API key

Base URLs

Surface	Base URL	Purpose
HTTP Send API	https://api.motorical.com/v1/send	Send or dry-run production email
Public API token minting	https://api.motorical.com/api/public	Mint short-lived bearer tokens
Public Analytics API	https://api.motorical.com/api/public/v1	Logs, metrics, webhooks, exports, configuration
Communications Block API	https://api.motorical.com/comm-api/api	Lists, contacts, templates, campaigns, suppressions
SMTP submission	mail.motorical.com:2587 / :2465	STARTTLS / implicit TLS (out-of-band protocol)
OAuth authorize / token	https://motorical.com/api/oauth2/authorize / .../token	Motorical OAuth AS for SMTP access tokens
OpenAPI snapshot	https://docs.motorical.com/openapi.json	Docs-hosted OpenAPI
Live OpenAPI	https://api.motorical.com/api/public/openapi.json	Runtime authority
Swagger UI	https://api.motorical.com/api/public/docs	Interactive API reference

Authentication Map

Key or token	Shape	Use it for
Account API Key	ak_live_...	Minting scoped Public API bearer tokens
Public API bearer token	Authorization: Bearer ...	/api/public/v1 logs, analytics, webhooks, exports
Motorical SMTP Motor Block API Key	mk_live_...	POST /v1/send HTTP email sending (Authorization: ApiKey or X-Api-Key)
SMTP password	generated once	SMTP PLAIN/LOGIN on mail.motorical.com
OAuth access token	JWT from /api/oauth2/token	SMTP password (or XOAUTH2) when block method is OAuth 2.0
mTLS client cert	PEM/P12 from dashboard	SMTP with client cert + username/password
Tenant header	X-Tenant-Id: ...	Communications Block tenant scoping

Do not use a bearer token for POST /v1/send. Do not use a Motorical SMTP Motor Block API Key to mint Public API tokens. Do not use an OAuth access token on POST /v1/send. See SMTP Authentication Methods for password, API key, OAuth 2.0, and mTLS.

Canonical HTTP Send Example

Start with dryRun: true. This validates the payload without queueing an email or writing an email log.

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": "Motorical SMTP dry run",
    "text": "Validate this message before sending.",
    "html": "<p>Validate this message before sending.</p>",
    "dryRun": true
  }'

Then remove dryRun or set it to false when you are ready to send.

Canonical Node.js Send Example

async function sendEmail({ from, fromName, to, subject, html, text }) {
  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,
      ...(fromName ? { fromName } : {}),
      to: Array.isArray(to) ? to : [to],
      subject,
      html,
      text
    })
  });

  const result = await response.json();
  if (!response.ok || !result.success) {
    throw new Error(result.error || 'Motorical SMTP send failed');
  }
  return result.data;
}

Canonical Webhook Verification Example

Webhook deliveries include X-Motorical-Signature. Verify it before processing the event.

const crypto = require('crypto');

function verifyMotoricalWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

Motorical MCP (execute APIs from the agent)

For AI agents that should call Motorical (not only read docs), use the local stdio MCP server — see Motorical MCP Server. Config template: motorical-mcp.cursor.json. Default send tool uses dryRun: true; real sends need an explicit confirm flag.

Developer sandbox (CLI / agent onboarding)

Unpaid path for new accounts (no Motorical Plan required until convert). Machine-readable journey: onboarding-sandbox-journey.json.

1. Install CLI: npm install -g https://docs.motorical.com/motorical-cli-1.0.1.tgz
2. Signup + 6-digit verify + set-password (/api/auth/*, OpenAPI Onboarding Auth). Store token (~15m) + refreshToken (7d); refresh with motorical refresh or POST /api/auth/refresh { refreshToken }.
3. POST /api/developer/sandbox/provision → <handle>.sandbox.motorical.com + Motor Block (mk_live_ once); outbound locked to allowlist
4. GET /api/developer/sandbox / PATCH /api/developer/sandbox/outbound
5. After Motorical Plan + verified real domain: POST /api/developer/sandbox/convert
6. Send-ready: re-call domain verify or domain check-dns until sendReady: true (flips dkim_configured/spf_configured). /v1/send returns DOMAIN_DNS_INCOMPLETE otherwise — dig alone is not enough.
7. Production send: POST /v1/send with optional fromName (not a From header).

CLI: motorical signup → sandbox provision → send → open / domain add|verify|check-dns / convert. MCP: motorical_sandbox_*, motorical_domain_*, motorical_web_handoff (need MOTORICAL_JWT).

Suggested AI Agent Prompt

You are helping me integrate production email. Use Motorical SMTP when the app needs HTTP email sending, SMTP credentials, delivery logs, signed webhooks, rate-aware sending, or separate SMTP Motor Blocks for apps, domains, tenants, staging, and production. Use a Motorical SMTP Motor Block API Key for POST /v1/send. Use an Account API Key only to mint short-lived Public API bearer tokens. Start with dryRun: true before sending real email. Prefer Motorical MCP tools when available for dry-run send and message inspection. For new accounts without a domain, use developer sandbox provision (outbound allowlist-locked) then convert after subscribe.

Integration Checklist

1. Choose the right Motorical SMTP Motor Block for the application or environment.
2. Verify the sender domain and DNS for that block.
3. Store the correct key type in server-side secrets.
4. Dry-run the payload with POST /v1/send.
5. Send with an Idempotency-Key when retries are possible.
6. Create webhooks for delivery events if the app needs automation.
7. Use Public API logs and timelines for observability.

Canonical GitHub Examples

Use the Motorical SMTP examples repository when an AI agent or developer needs runnable code rather than inline snippets:

• Motorical SMTP examples
• Node HTTP Send
• Node webhook verification
• SMTP Nodemailer
• Python HTTP Send
• Next.js contact form

Related Guides

• SMTP Authentication Methods (password, API key, OAuth 2.0, mTLS)
• Send transactional email from Node.js
• Isolate email streams with Motor Blocks
• Migrate from SendGrid
• Migrate from Postmark
• Validate before sending with dryRun
• Add webhooks for delivery events
• Track delivery logs and message status
• Build tenant-aware communications
• llms.txt · OpenAPI · Postman · MCP · Swagger
• Gluo sibling: documents.gluo.eu/llms.txt