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 list, 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 Template.
3. 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. Build your email content using the Email Editor.
5. Save the template.

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

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 using the /var command, 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
• The recipient email address
• Any variables the template needs

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