Transactional Emails
Transactional emails are one-time, programmatic emails sent to users based on specific triggers in your application. Unlike marketing emails (broadcasts and sequences), transactional emails are service-related messages that users expect to receive.
Common examples include:
- Password reset emails
- OTP/verification codes
- Account confirmation emails
- Order receipts and shipping notifications
- Security alerts
Setting Up Transactional Emails
To send transactional emails, you need an Access Token with transactional email permissions. Broadcast automatically creates a default transactional email token when you create a channel.
Navigate to Access Tokens in the sidebar to view and manage your tokens.
Each token displays: - Name: A label to identify the token’s purpose - Token: The masked API key (first and last 4 characters visible) - Permissions: What the token can access (e.g., Transactional read/write)
Sending a Test Email
Before integrating with your application, you can test your setup directly from Broadcast. Navigate to Transactional in the sidebar.
If you have an access token configured, you’ll see a Try it now card with a button to send a test email to your account email address.
The page also displays a ready-to-use cURL command that you can copy and use in your terminal or integrate into your application.
Viewing Transactional Emails
After sending transactional emails, they appear in a list view where you can:
- Filter by email: Search for emails sent to a specific recipient
- Filter by status: View all, sent, queued, pending, or failed emails
- Monitor in real-time: The “Live” indicator shows real-time updates as emails are processed
Click on any email to view its details, including:
- Recipient information: Email address and name
- Email server: Which server was used to send the email
- Timeline: When the email was created, queued, and sent
- Email preview: View the rendered email content
2.52+
The preview fills in the email’s Liquid with mock data, not with the recipient’s data, and has the Preview data panel to switch each condition. See Broadcast Emails (“Previewing Personalized Content”). A body that is not a full HTML document (labeled plain text on the email’s page) is sent in the standard email layout. When such a body uses Liquid, the preview shows it in that layout, with the channel footer when the unsubscribe link is on.
You can also resend any transactional email directly from the detail view.
2.49+
An email sent through a test server has a Captured, not delivered badge next to its status, in the list, on its page and on the dashboard. When the test inbox is available, the badge links to it. Nobody received the email.
Note
Send transactional emails through a server that does not send broadcasts. Then a large broadcast cannot delay a password reset or a login code. See Email Server Rate Limits.
Email Status
Transactional emails go through the following statuses:
| Status | Description |
|---|---|
| Pending | Email created but not yet queued for sending |
| Queued | Email is in the queue, waiting to be sent |
| Sent | Email was successfully delivered to the mail server |
| Failed | Email failed to send (check error details for more info) |
2.49+
When the SMTP server refuses the address because it does not exist (for example “550 5.1.1 user unknown”), the email is Failed and Broadcast records a hard bounce, the same as a bounce webhook. The address is added to the channel suppression list, and a subscriber with that address is deactivated. A hard bounce blocks transactional email only when the channel’s “Hard bounces also block transactional email” setting is on. See Suppression Lists.
If the email server is at its full hourly limit, a transactional email stays Queued and Broadcast tries again every minute. After 30 minutes of waiting, every page of the channel shows a notice. After 24 hours it is marked Failed with the reason “Email server at hourly limit: no room for 24 hours, giving up”. See Email Server Rate Limits.
Data Retention
2.53+
By default, Broadcast keeps every transactional email it sends. To keep them for a limited time, set Delete transactional email after (days) under Settings → General Channel Settings → Data Retention. The value is a number of days from 7 to 3650. Leave the field empty to keep transactional email forever.
Once a day, Broadcast deletes the channel’s transactional emails that are Sent or Failed and older than that number of days. The age of a sent email counts from when it was sent. The age of a failed email counts from when it failed. With each email it deletes the rows that copy its recipient address, subject or body:
- The send record, with its open and click data
- The webhook events for the email and their delivery history
- The error log entries and the custom headers of the email
- The channel error the email failed with, when no other email or broadcast still uses it
The dashboard counts and history for those emails go with them.
Broadcast never deletes these:
- Pending and Queued emails, however old. That includes scheduled emails and emails that wait for room on the email server.
- Subscribers, suppression list entries and unsubscribes. They keep blocking an address after its emails are gone.
An email with a webhook delivery that is still retrying or held is not deleted yet. Broadcast keeps it until that delivery finishes or gives up, and deletes it on a later daily run.
Deleted emails stay in your database backups until those backups rotate out. See Backup & Recovery.
Sending via API
To send transactional emails programmatically, use the API endpoint with your access token. See the Transactional Email API documentation for complete details.
Quick example:
curl "https://your-broadcast-domain.com/api/v1/transactionals.json" \ -X POST \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "user@example.com", "subject": "Your verification code", "body": "Your code is: 123456" }'
Unsubscribe Behavior
Transactional emails are fundamentally different from marketing emails. They include essential service-related messages that users need to receive regardless of their marketing preferences.
Transactional emails will always be delivered, even if the recipient has unsubscribed from marketing emails. This follows industry standards (CAN-SPAM, GDPR) which distinguish between marketing communications and service-related transactional messages.
However, transactional emails will still be blocked in these cases:
- Redacted subscribers: If a subscriber has been redacted (GDPR data deletion), transactional emails will not be sent to comply with data protection regulations.
- Suppression lists: If the address is on the channel or global suppression list as a manual, imported or API entry, transactional emails will not be sent. A hard bounce blocks them only when the channel setting “Hard bounces also block transactional email” is on. Spam complaints never block them.
