---
name: saasco-transactional-emails
description: "Audits a product codebase for transactional emails and builds templates for supported account, billing, order, and service events. Use when choosing which transactional emails a product needs, filling gaps in existing emails, or wiring chosen templates to the Saasco send API when requested."
compatibility: "Requires access to the application repository. Sending requires a Saasco project, a verified sending domain, and a server-side project API key."
---
# Build transactional email templates

Work in the user's application repository. Produce templates the application can render and local fixtures the user can preview. The [Saasco transactional email guide](https://www.saasco.com/docs/transactional-emails) covers sending from a project and checking delivery.

## 1. Trace the events and existing sends

Start with the repo instructions, email templates and mail adapters. Search for sends in auth callbacks, billing or order webhooks, background jobs, and any linked platform integrations. For each candidate, trace the event to the code that confirms it, where its recipient and data come from, and which component or provider already sends a message. Include messages sent by external auth, billing, or commerce providers when the integration or config shows that they are enabled.

Build a short inventory with the proposed message, trigger and file path, recipient, available data, and current sender. Mark gaps separately from existing messages that would need a replacement. If a trigger or sender cannot be confirmed from the repo, say what you could verify and leave it out of the implementation until clarified.

## 2. Choose messages that fit the product

Prioritize critical account actions and confirmations for money or orders. Use the user’s requested list when given. For a general request, select a small set of gaps with confirmed triggers and data, and state your choice. For an audit-only request, stop at the inventory.

Look for these events as you read the code.

- **Account and security**. Follow sign-up verification, password reset, or a new-device event to the existing auth code. Reuse its token or link generation and use its real expiration rules.
- **Billing and subscriptions**. Look for successful payment, processed refund, or a confirmed subscription change. Read amounts, currency, and dates from the authoritative billing record.
- **Orders and fulfillment**. Use the existing order, shipment, or cancellation state. Include tracking only when a shipment actually has a tracking URL.
- **Bookings and support**. Use confirmed appointment details and time zone, or a message tied to an existing support request and its established reply path.

Keep each message focused on the event and any action the recipient needs to take. Route newsletters, upsells, onboarding sequences, and cart reminders through the product's marketing channel.

## 3. Implement and preview the templates

Reuse the repo's email renderer, layout, brand assets, and copy patterns. Build each chosen template with explicit inputs, a subject, rendered HTML, and a plain-text version. Use URLs from application configuration and derive content from the same data the event already uses. Omit optional details when the application has no value for them. Use dummy data and inert links in fixtures, especially for authentication emails.

Use the project's existing preview or test workflow. Render each template with representative data and any important missing optional fields. Check the subject, primary link, plain text, and formatting of dates, amounts, and time zones where applicable.

## 4. Wire sending only when requested

Template work can stop at rendering and local previews. If the user also asks to connect sending, reuse the existing server-side mail, job, or event path. Preserve the provider that owns each send until the user approves replacing it, then make the change in one place to avoid duplicate messages. Keep auth tokens, verification, and expiration logic with the application’s auth provider.

Use the [send endpoint](https://www.saasco.com/docs/transactional-emails/send-transactional-email) with the project ID, its server-side API key, and an address on a verified sending domain. Pass the rendered content, an optional stable `category`, and one `idempotencyKey` per intended email based on the event or persisted send ID. Preserve the exact rendered payload across retries. Handle failures with the repo's existing retry policy and keep keys, message bodies, and auth links out of logs.

Test the integration with a mocked transport. When the user asks you to send a sample email, send it from their project to an inbox they control. Check the returned ID and the matching send in the project’s dashboard or [get endpoint](https://www.saasco.com/docs/transactional-emails/get-transactional-email).

Report the templates built, where they render, the source event for each, and how to preview or test them. Call out any messages already covered by another provider and any send paths still waiting to be connected.
