Skip to main content
Transactional send lets your application dispatch a single email to a contact on demand. Use it for confirmations, alerts, password resets, or any message that is triggered by an action your user just took.

​
When to use transactional send

  • You need to send immediately after an application event.
  • The message is specific to one contact and one moment.
  • The content depends on data that is only available at send time (order ID, token, amount, etc.).
For scheduled, behavior-driven sequences, use workflows instead.

​
Request structure

Call POST /client/send with your API key and the following fields: 
{
  "template_id": 123,
  "to": {
    "email": "customer@example.com",
    "name": "Jane Doe"
  },
  "vars": {
    "order_id": "ORD-9001",
    "total": "$49.99",
    "estimated_delivery": "2026-06-30"
  }
}
You can also use template_name instead of template_id if you prefer to reference templates by name.

​
Variable resolution

When MailerPath processes the send request, it builds the variable set in this order:
  1. Contact fields from the matched contact record.
  2. Client settings (brand, sender, timezone, etc.).
  3. System-generated values (unsubscribe link, view in browser URL).
  4. Your custom vars — these override any of the above if keys collide.
For the full variable reference, see Templates and personalization.

​
Subscription check

MailerPath checks the recipient’s subscription state before sending.
  • Unsubscribed contacts are skipped by default.
  • The sent email record reflects the skip reason when applicable.

​
Idempotency

Use unique values for idempotency_key when your application may retry the same request: 
{
  "template_id": 123,
  "to": {"email": "customer@example.com"},
  "vars": {"order_id": "ORD-9001"},
  "idempotency_key": "send-order-9001-customer-20260623"
}
Duplicate requests with the same key are safely rejected after the first success.

​
Authentication

All transactional send requests require an enabled API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
See API keys for setup.

​
What happens after the request

  1. MailerPath creates a sent email record with status queued.
  2. The email is dispatched to the email provider.
  3. Status updates to sent, and then delivered, opened, or bounced as webhook events arrive.
Track these outcomes in your sent email history: Sent emails and delivery status.

​
Common issues

  • 422 — missing required fields, invalid template ID, or unsubscribed contact.
  • 401 — missing or disabled API key.
  • 409 — duplicate idempotency key for an already-sent message.
For more send and delivery failure patterns, see Common API issues.