Transactional Emails

Transactional emails are one-to-one messages triggered by your application — things like password resets, order confirmations, welcome emails, or account notifications. Unlike marketing campaigns sent to a topic or segment, transactional emails are sent to a specific contact in response to an action they took.

Transactional vs. marketing emails

Creating transactional templates

1. Open Mail > Transactional.
2. Click New Transactional Email.
3. In the Create Transactional Email dialog, enter a name and a slug — the slug is a short, unique identifier you'll reference when sending (e.g., "welcome-email" or "password-reset").
4. Click Create & Edit to open the template in the Email Editor.
5. Build your email content and save your work.
6. Publish the template. New templates start as a Draft, and the send API will not send a draft. Use the Publish action in the editor to make it sendable — an unpublished or empty template is rejected at send time (see Publishing).

Slugs

The slug is how your application identifies which template to send. Choose something descriptive and stable:

• "welcome-email" — for new user registration
• "password-reset" — for password recovery
• "order-confirmation" — for purchase receipts

Publishing and review

A transactional template moves through three states:

A template must be published before the API will send it. If you call the send endpoint with a template that isn't published, the request is rejected (template_not_published); a published template with no rendered HTML content is rejected too (template_no_content). Publishing a draft is the single most common fix for a transactional send that won't go out.

When you click Publish in the editor, the content scanner runs on the subject and HTML. If it flags the content as suspicious, the template lands in Awaiting review instead of going live — it stays unsendable until an admin approves it. Severely flagged content is blocked outright and won't publish at all. Use Unpublish to take a live template back to draft for edits.

The transactional template list and its status filter label this same state Pending Review, while the editor calls it Awaiting review — both refer to the identical held status.

Variables

Transactional templates can include dynamic variables that are populated with data you provide at send time. This is how you include order details, account information, or any data specific to the trigger event.

Common variable uses:

• Contact fields (first name, email)
• Custom data passed at send time (order total, tracking link, reset URL)
• Conditional content based on variable values

Insert variables in the editor by typing {{ or @ to open the variable picker, just like in marketing templates.

Sending transactional emails

Transactional emails are sent through the API. Your application makes an API call specifying:

• The template slug to use (or its transactionalId)
• The recipient email address
• Any template variables, passed as the dataVariables object

See the API documentation for endpoint details, request format, and code examples.

Monitoring sends

Track your transactional email delivery in the dashboard:

• View send status for individual transactional emails
• Monitor delivery rates and bounce rates
• Identify templates that may have rendering or delivery issues

Attachments

Transactional emails can include file attachments — useful for invoices, receipts, tickets, or any document the recipient needs.

Adding attachments in the dashboard

When configuring a transactional template, use the attachment picker to select files from your Media Library. This is convenient for static attachments that don't change per recipient.

Adding attachments via the API

For dynamic attachments, pass an attachments array in your API request:

{
  "slug": "order-confirmation",
  "email": "customer@example.com",
  "attachments": [
    {
      "filename": "invoice.pdf",
      "url": "https://example.com/invoices/12345.pdf",
      "contentType": "application/pdf"
    }
  ]
}

Each attachment can provide file content as a base64 string (content) or a URL to fetch from (url). See the Transactional API docs for the full field reference.

Limits: maximum 10 attachments, 10 MB total size.

Best practices

• Keep transactional emails focused — include only the information the recipient needs. A password reset email should have the reset link, not a promotional sidebar.
• Test with real data — send test emails with realistic variable values to make sure your template handles different data correctly (long names, missing fields, etc.).
• Set up error handling — your application should handle API errors gracefully. If a transactional email fails to send, log the error and consider a retry strategy.
• Use clear sender names — transactional emails should come from a recognizable sender so recipients trust and open them.

Next steps

• Email Editor — build your transactional templates
• Email Templates — understand the template system
• Deliverability — ensure your transactional emails reach inboxes
• Media Library — manage attachments and images in one place
• API documentation — integrate transactional sends into your app