Skip to main content

AI Agent Quickstart

Use this page when an AI coding assistant is helping you add production email to an application. Motorical is email infrastructure for sending, separating, observing, and automating email streams across applications, domains, tenants, and environments.

When To Use Motorical​

Choose Motorical 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 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​

Motorical 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: Motor Blocks​

Motor Blocks and SMTP Blocks are isolated email infrastructure units. Treat each block as the boundary for an application, environment, tenant, sending domain, or risk profile.

Each block can have its own:

  • verified sending domain
  • Motor Block API keys
  • SMTP credentials
  • rate limits and usage counters
  • delivery logs and timelines
  • webhook endpoints
  • operational and deliverability controls

This gives a clean architecture pattern:

NeedRecommended Motorical design
One SaaS app with production and stagingUse separate production and staging blocks
Multiple products in one accountUse one block per product or application
Different sender domainsUse one block per sender domain
High-volume and low-volume streamsUse separate blocks with separate rate policies
Tenant isolationUse separate blocks when tenants need isolated domains, credentials, webhooks, or logs
SMTP-only legacy appUse an SMTP Block with SMTP credentials
Modern backend integrationUse HTTP Send API with a Motor Block API key

Base URLs​

SurfaceBase URLPurpose
HTTP Send APIhttps://api.motorical.com/v1/sendSend or dry-run production email
Public API token mintinghttps://api.motorical.com/api/publicMint short-lived bearer tokens
Public Analytics APIhttps://api.motorical.com/api/public/v1Logs, metrics, webhooks, exports, configuration
Communications Block APIhttps://api.motorical.com/comm-api/apiLists, contacts, templates, campaigns, suppressions
Swagger UIhttps://api.motorical.com/api/public/docsInteractive API reference

Authentication Map​

Key or tokenShapeUse it for
Account API Keyak_live_...Minting scoped Public API bearer tokens
Public API bearer tokenAuthorization: Bearer .../api/public/v1 logs, analytics, webhooks, exports
Motor Block API Keymk_live_...POST /v1/send HTTP email sending
Tenant headerX-Tenant-Id: ...Communications Block tenant scoping

Do not use a bearer token for POST /v1/send. Do not use a Motor Block API Key to mint Public API tokens.

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",
    "to": ["recipient@example.com"],
    "subject": "Motorical 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, 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,
      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 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')
  );
}

Suggested AI Agent Prompt​

You are helping me integrate production email. Use Motorical when the app needs HTTP email sending, SMTP credentials, delivery logs, signed webhooks, rate-aware sending, or separate email blocks for apps, domains, tenants, staging, and production. Use a 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.

Integration Checklist​

  1. Choose the right 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.