Transactional API

Send one-off transactional emails (password resets, OTPs, receipts, order confirmations, and more) via the REST API. Design reusable email templates in the dashboard and integrate them into your existing application or workflow.

Your contacts remain in your own system — only the template ID and merge variables are required for each send request.

Email templates must be created and managed in Transactional → Email Templates. Once a template is created, send emails using POST /api/v1/transactional/send by providing the template ID and required parameters.

• check_circleTransport: Authorization: Bearer <api_key> or X-Api-Key.
• check_circleAPI key permission: transactional.
• check_circlePlan: the tenant’s active plan must have transactional_enabled.

Common errors:

{ "status": "error", "reason": "Your current plan does not include Transactional Email." }

{ "status": "error", "reason": "API key does not have transactional permission." }

All tenant routes are under /api/v1/transactional and use the api-v1-transactional limiter (60 requests/min per API key). Failed validation on these routes returns HTTP 422 with { "status": "error", "reason": "<first error>" }.

Open Transactional → Email Templates (/transactional/message-types; /transactional/messages redirects there). Each row is a transactional_messages record used for send content and analytics grouping.

Dashboard save stores:

• check_circlename (required)
• check_circlesubject (required, max 998 characters) — merge tokens allowed
• check_circlebody_html (required) — HTML template; merge tokens allowed
• check_circlebody_text (optional) — if omitted, the dashboard derives plaintext from the HTML
• check_circleenabled — disabled templates cannot be sent
• check_circletrack_opens / track_clicks — dashboard-created templates set both to true
• check_circlesource — dashboard creates manual
• check_circleslug — dashboard creates null; send and list identify templates by numeric id
• check_circlerequired_variables — dashboard create stores []. The send API still enforces this list when it is non-empty

A template is sendable only when subject is non-empty and the HTML has visible text or an <img> tag. Otherwise send returns HTTP 422: This message has no saved template.

GET /api/v1/transactional/messages returns metadata including subject. It does not return body_html or body_text.

POST /api/v1/transactional/send

Queues delivery through a mailbox you own. Subject, HTML, and optional plaintext are taken from the saved template after {{token}} substitution.

Required

Optional

Prohibited (HTTP 422): subject, message, text. Content cannot be overridden on the send call.

Statuses

• check_circle202 — new send queued (idempotent_replay: false)
• check_circle200 — existing send returned for the same idempotency_key and matching payload (idempotent_replay: true); the outbound job is not dispatched again
• check_circle409 — idempotency_key was already used for a different send (different template, recipient, from, reply-to, variables, or X-* headers)

data.status reflects queue/SMTP acceptance (queued → sending → sent, or failed / bounced). Inbox confirmation is separate: check delivered_at and delivery_events (populated by provider delivery webhooks).

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/transactional/send" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transactional_message_id": 1,
    "to": { "email": "user@example.com", "name": "Ada" },
    "from": { "email": "noreply@yourdomain.com" },
    "variables": { "first_name": "Ada" },
    "idempotency_key": "order-42-welcome"
  }'

{
  "status": "success",
  "data": {
    "id": 101,
    "transactional_message_id": 1,
    "status": "queued",
    "channel": "transactional",
    "from_address": "noreply@yourdomain.com",
    "from_name": "Acme",
    "to_addresses": ["user@example.com"],
    "subject": "Hello Ada",
    "message_id": null,
    "idempotency_key": "order-42-welcome",
    "failure_reason": null,
    "queued_at": "2026-09-04T12:00:00.000000Z",
    "sent_at": null,
    "delivered_at": null,
    "last_deferred_at": null,
    "created_at": "2026-09-04T12:00:00.000000Z",
    "delivery_events": []
  },
  "idempotent_replay": false
}

data.subject is the rendered subject after variable substitution.

Send-time error reasons (examples)

Transactional HTML does not get List-Unsubscribe headers. Open-pixel and click rewriting follow the template’s track_opens / track_clicks flags.

Attachments

"attachments": [
  {
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "content": "<base64>"
  }
]

Limits come from config/transactional.php (env overrides in parentheses):

• check_circlecount: TRANSACTIONAL_ATTACHMENTS_MAX_COUNT (default 5)
• check_circleper file: TRANSACTIONAL_ATTACHMENTS_MAX_BYTES (default 5 MiB)
• check_circletotal: TRANSACTIONAL_ATTACHMENTS_MAX_TOTAL_BYTES (default 15 MiB)
• check_circleMIME allowlist: PDF, JSON, plain text, CSV, PNG, JPEG, GIF, WebP, Word, Excel

Invalid base64 or a disallowed content_type returns HTTP 422.

Variables

Use {{variable_name}} in the template subject and body.

If the tenant has any rows in Variable Manager (/transactional/variables):

• check_circleevery {{token}} in the template (and every required_variables key) must exist in the registry
• check_circlesend values must match the registered data_type
• check_circleregistry default_value is applied when the send payload omits the key or sends empty

If the registry is empty, only required_variables on the message (when set) are enforced; other tokens are substituted as provided.

Registered types: string, integer, date, url, boolean, email, currency.

POST /api/v1/transactional/variables

Creates a typed registry entry. Duplicate key returns HTTP 409 unless overwrite=true (then HTTP 200). New keys return HTTP 201. source on the record is api.

curl --fail-with-body --silent --show-error \
  -X POST "$APP_URL/api/v1/transactional/variables" \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "otp",
    "data_type": "integer",
    "overwrite": false
  }'

{
  "status": "success",
  "data": {
    "id": 1,
    "key": "otp",
    "data_type": "integer",
    "default_value": null,
    "source": "api"
  },
  "overwritten": false
}

{
  "status": "error",
  "reason": "A variable with this key already exists. Pass overwrite=true to replace it.",
  "data": { "key": "otp", "id": 1 }
}

GET /api/v1/transactional/messages

Paginated list for the tenant (enabled and disabled). Ordered by name.

Query: per_page — integer 1–100, default 50.

Response is a Laravel resource collection (data, links, meta). Each item:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  "$APP_URL/api/v1/transactional/messages"

{
  "data": [
    {
      "id": 1,
      "name": "Password Reset",
      "slug": null,
      "description": null,
      "subject": "Reset your password",
      "enabled": true,
      "required_variables": [],
      "track_opens": true,
      "track_clicks": true,
      "source": "manual",
      "created_at": "2026-09-04T12:00:00.000000Z",
      "updated_at": "2026-09-04T12:00:00.000000Z"
    }
  ]
}

HTML/plaintext bodies are omitted.

GET /api/v1/transactional/sends/{id}

Returns one outbound row if it belongs to the tenant and channel is transactional. Otherwise HTTP 404.

Uses the same send resource as POST /send.

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer YOUR_32_CHARACTER_API_KEY" \
  "$APP_URL/api/v1/transactional/sends/101"

{
  "status": "success",
  "data": {
    "id": 101,
    "transactional_message_id": 1,
    "status": "sent",
    "channel": "transactional",
    "from_address": "noreply@yourdomain.com",
    "from_name": "Acme",
    "to_addresses": ["user@example.com"],
    "subject": "Hello Ada",
    "message_id": "<abc@mail.example>",
    "idempotency_key": "order-42-welcome",
    "failure_reason": null,
    "queued_at": "2026-09-04T12:00:00.000000Z",
    "sent_at": "2026-09-04T12:00:03.000000Z",
    "delivered_at": "2026-09-04T12:00:05.000000Z",
    "last_deferred_at": null,
    "created_at": "2026-09-04T12:00:00.000000Z",
    "delivery_events": [
      {
        "event_type": "delivered",
        "provider": "mailcow",
        "occurred_at": "2026-09-04T12:00:05.000000Z",
        "diagnostic": null
      }
    ]
  }
}

status: sent means the provider accepted the message. delivered_at / delivery_events confirm downstream delivery when webhooks are configured.

• check_circleEmail Templates — design subject/HTML used by send
• check_circleVariables — typed registry; duplicate keys need overwrite confirmation (API: 409 unless overwrite=true)
• check_circleSends — outbound history
• check_circleAnalytics — funnel metrics (including Delivered / Deferred when provider events exist); CSV / Excel / JSON export
• check_circleAPI Logs — redacted request/response logs; purge with transactional:purge-api-logs (retention: TRANSACTIONAL_API_LOGS_RETENTION_DAYS, default 30)

Provider callbacks are ingested at POST /api/webhooks/outbound-delivery (not tenant API keys).

Authenticate with X-Outbound-Delivery-Secret or Authorization: Bearer matching OUTBOUND_DELIVERY_WEBHOOK_SECRET.

Payload fields: provider, provider_event_id (idempotent), event_type (delivered | deferred | rejected | failed | complaint), plus message_id and/or outbound_email_id.

Matched delivered events set outbound_emails.delivered_at once; deferred updates last_deferred_at. Unknown message ids are logged and ignored. These fields and a summarized delivery_events list are exposed on GET /api/v1/transactional/sends/{id} and on the send response from POST /send.

Admins can open /admin/transactional/analytics for cross-tenant funnel, tenant breakdown, templates, recent sends, and CSV/JSON export.

On the MailAPI MCP server (transactional permission + plan entitlement):

The SMTP submission gateway authenticates with the same API key but sends the MIME subject and body as submitted. It does not load dashboard templates. Use REST when you want template IDs and variables; use SMTP when the client already builds the full message.

PHP (Laravel HTTP client)

Http::withToken($apiKey)
    ->post(config('app.url').'/api/v1/transactional/send', [
        'transactional_message_id' => 1,
        'to' => ['email' => 'user@example.com'],
        'from' => ['email' => 'noreply@yourdomain.com'],
        'variables' => ['first_name' => 'Ada'],
    ]);

Node.js

await fetch(`${process.env.APP_URL}/api/v1/transactional/send`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transactional_message_id: 1,
    to: { email: 'user@example.com' },
    from: { email: 'noreply@yourdomain.com' },
    variables: { first_name: 'Ada' },
  }),
});

Python

import requests

requests.post(
    f"{APP_URL}/api/v1/transactional/send",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "transactional_message_id": 1,
        "to": {"email": "user@example.com"},
        "from": {"email": "noreply@yourdomain.com"},
        "variables": {"first_name": "Ada"},
    },
)

• check_circleCreate the template in Email Templates, then copy its numeric id into transactional_message_id.
• check_circleUse idempotency_key for retries from your application.
• check_circleRegister merge keys in Variable Manager before sending if you use the registry.
• check_circleKeep transactional content free of marketing unsubscribe requirements.
• check_circleMonitor Transactional → Analytics for sent/failed/bounced/opens/clicks.
• check_circleRespect mailbox and plan sending limits; deferred sends are retried by the outbound queue.