Sending Transactional Emails

Send one-off transactional emails via the API

Sending Transactional Emails

Transactional emails are triggered by specific actions — password resets, order confirmations, account notifications — and are sent to individual recipients in real time. Unlike marketing campaigns, transactional emails are not subject to unsubscribe preferences and are delivered with high priority.

Sending a transactional email

POST /api/v1/transactional/send

{
  "to": "jane@example.com",
  "from": "noreply@yourdomain.com",
  "subject": "Your order #1234 has shipped",
  "html": "<h1>Order Shipped</h1><p>Your order is on its way!</p>",
  "text": "Your order is on its way!",
  "tags": ["order-shipped"]
}

Request parameters

Field	Type	Required	Description
`to`	string	Yes	Recipient email address
`from`	string	Yes	Sender email (must be on a verified domain)
`subject`	string	Yes	Email subject line
`html`	string	Yes*	HTML body of the email
`text`	string	No	Plain text fallback (auto-generated from HTML if omitted)
`reply_to`	string	No	Reply-to email address
`tags`	array	No	Tags for categorizing and filtering in analytics
`headers`	object	No	Custom email headers (key-value pairs)
`metadata`	object	No	Key-value metadata stored with the send (not included in email)

* Either html or text must be provided. If you provide html only, a plain text version is generated automatically.

Using merge variables

You can include merge variables in your HTML and subject line:

{
  "to": "jane@example.com",
  "from": "noreply@yourdomain.com",
  "subject": "Welcome, {{name}}!",
  "html": "<p>Hi {{name}}, your account is ready.</p>",
  "merge_vars": {
    "name": "Jane"
  }
}

Merge variables use double curly brace syntax: {{variable_name}}. Any unresolved variables are replaced with an empty string.

Response

A successful send returns:

{
  "success": true,
  "data": {
    "message_id": "msg_abc123def456",
    "status": "queued"
  }
}

The email is queued for immediate delivery. Use the message_id to track delivery status via webhooks.

Domain verification

The from address must use a domain that has been verified in your Mailnaptic account with valid SPF, DKIM, and DMARC records. Sending from an unverified domain returns a 400 error.

Rate limits

Transactional email endpoints have a higher rate limit than general API endpoints: 300 requests per minute per API key. For burst scenarios (e.g., hundreds of order confirmations at once), Mailnaptic queues emails internally and processes them in order.

Tracking

Open and click tracking are disabled by default for transactional emails to avoid interfering with functional links (e.g., password reset URLs). You can enable tracking per request:

{
  "track_opens": true,
  "track_clicks": false,
  ...
}

Best practices

Keep transactional emails focused: Include only the essential information. Do not add promotional content — it can trigger spam filters and violates CAN-SPAM if the recipient has unsubscribed from marketing.
Always include a text fallback: While auto-generation works, a hand-crafted plain text version ensures the best experience for text-only email clients.
Use tags: Tag emails by type (password-reset, order-confirmation, invoice) to analyze delivery performance by category.
Monitor bounces: Subscribe to email.bounced webhooks to catch invalid addresses and update your application accordingly.

Scope required: The API key must have the transactional:send scope. This scope does not grant access to campaigns or contacts.

Sending Transactional Emails