# Transactional Email Operations

Transactional email is for messages a person needs because of an action, request, or account state: password resets, receipts, login codes, account notices, and order confirmations.


> ⚠️ **Warning**
> Do not use transactional sends for newsletters, product updates, lifecycle campaigns, or winback messages. Use broadcasts, sequences, workflows, and consent-aware marketing paths for those.


---

## What Counts As Transactional {{ id: 'what-counts-as-transactional' }}

Good transactional candidates:

- Password reset and magic login links.
- Email verification.
- Receipts and invoices.
- Order confirmations and shipping updates.
- Security alerts.
- Required account or policy notices.

Marketing candidates:

- Product updates.
- Promotional offers.
- Educational sequences.
- Re-engagement campaigns.
- Newsletters.

Read [Marketing vs Transactional](/docs/deliverability/marketing-vs-transactional) when the boundary is unclear.

---

## Before You Send {{ id: 'before-you-send' }}

Complete these steps before production traffic:

1. Set up sender authentication in Bento.
2. Verify the `from` address is an author in your account.
3. Store API keys server-side.
4. Add rate limits to user-triggered actions such as password resets, login links, invites, and form submissions.
5. Send test emails to real inboxes and check rendering.
6. Confirm your app cannot send duplicate emails on retries.


> No separate public sandbox mode is documented today. Use a staging Bento site or seed contacts, then follow [How to Test Email Flows](/docs/howtos/test_flows) before production traffic reaches the workflow.


---

## Send Paths {{ id: 'send-paths' }}

Use one of these paths:

| Path | Best for | Docs |
| --- | --- | --- |
| SDK transactional method | Most app integrations. | [SDKs](/docs/sdks) |
| Emails API | Direct HTTP integrations. | [Emails API](/docs/emails_api) |
| CLI | Scripts and operational sends. | [Bento CLI](/docs/integrations/cli) |
| Workflow transactional email | Confirmation emails and product flows inside Bento. | [Workflows](/docs/concepts/workflows) |

The Emails API queues requests quickly, then sends them through Bento's priority pipeline.

---

## Templates And Personalization {{ id: 'templates-and-personalization' }}

Keep transactional templates stable and boring in the best way:

- Use clear subjects.
- Include both the reason for the email and the action the user requested.
- Keep links on your authenticated domain where possible.
- Use minimal personalization.
- Avoid user-controlled HTML in names, company fields, or custom fields.


> 🚨 **Important**
> User-controlled personalization can become an injection vector. For security-sensitive emails, avoid dynamic content unless you sanitize it in your own app first.


---

## Unsubscribes And Suppressions {{ id: 'unsubscribes-and-suppressions' }}

Transactional messages can be sent even when a subscriber has unsubscribed from marketing if the email is truly required.

Rules of thumb:

- Use transactional sends only for necessary account or purchase communication.
- Do not use transactional flags to bypass marketing consent.
- Respect hard bounces, complaints, and blocked addresses.
- Do not delete unsubscribers just to recreate them later.

For broader contact rules, read [Contacts And Consent](/docs/operations/contacts-consent).

---

## Status And Bounces {{ id: 'status-and-bounces' }}

When a transactional email does not arrive:

1. Check the recipient profile activity.
2. Confirm the sender domain is authenticated.
3. Check bounces and suppressions.
4. Search for content or link warnings.
5. Check whether your app sent duplicate or malformed requests.

Use [Bounces](/docs/deliverability/bounces), [Sending Limits](/docs/deliverability/sending_limits), and [Troubleshooting](/docs/troubleshooting) for deeper diagnosis.

---

## Unsupported Patterns {{ id: 'unsupported-patterns' }}

Avoid these patterns:

- File attachments through the Emails API. Link to files instead.
- URL shorteners.
- Sending from unapproved or unauthenticated addresses.
- Client-side API calls with secret keys.
- Large fan-out sends from user-facing requests.
- Reusing transactional sends for promotional campaigns.

---

## Abuse Controls {{ id: 'abuse-controls' }}

Protect every app endpoint that can trigger an email:

- Add per-user and per-IP rate limits.
- Add CAPTCHA, bot checks, or honeypots to public forms.
- Queue sends so traffic spikes do not create email spikes.
- Do not include attacker-controlled values in the subject.
- Log request source, user ID, and message type.

---

## Launch Checklist {{ id: 'launch-checklist' }}

- [Emails API](/docs/emails_api) or SDK send works in staging.
- Sender authentication is valid.
- `from` address is an author.
- User-facing trigger is rate limited.
- Retries cannot create duplicate emails.
- Bounces and complaints have an owner.
- Support knows where to inspect a failed transactional send.

## Related docs

- [Emails API](/docs/emails_api)
- [How to Test Email Flows](/docs/howtos/test_flows)
- [Marketing vs Transactional](/docs/deliverability/marketing-vs-transactional)
- [Mandated Emails](/docs/deliverability/mandated_emails)
- [Bounces](/docs/deliverability/bounces)