# Sending Transactional Emails

Send one-off transactional emails via the API

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": "

# Order Shipped

Your order is on its way!

",
  "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": "Hi {{name}}, your account is ready.

",
  "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.
