# Transactional Emails

Build transactional email templates for events your backend already handles, then send a sample email and confirm delivery. Your application renders the message, and Saasco delivers it and records delivery events.

## Build templates with your agent

Open your application repository in your coding agent. The skill traces what already sends email, finds gaps backed by real events, and builds templates with sample data you can preview locally. [Install the transactional email templates skill](/docs/skills/saasco-transactional-emails).

**Build transactional email templates**

```text
Review this repository and build transactional email templates for the most important events my product already handles. Check which messages already send, use sample data I can preview, and leave sending disabled. Read https://www.saasco.com/.well-known/agent-skills/saasco-transactional-emails/SKILL.md and follow it.
```

## 1. Get your project ID and API key

To send email, you’ll need a verified sending domain on your project. If you still need one, follow the [sending domain setup guide](/docs/domains/add), then return here.

1. Open your project and check that it has a positive balance in **Project Settings → Billing**.
2. Copy the project ID from **Project Settings → Project**. In **Project Settings → API keys**, [create a key](/docs/api#generate-an-api-key) for the same project.
3. Load the project ID as `SAASCO_PROJECT_ID` and its key as `SAASCO_API_KEY` in your terminal or backend environment. Keep the key in server-side configuration.

## 2. Send one email to yourself

Replace `from` with an address on your verified domain and `to` with an inbox you control. Use a unique `idempotencyKey` for this send.

```bash
curl --fail-with-body --silent --show-error \
  --request POST "https://www.saasco.com/api/v2/projects/$SAASCO_PROJECT_ID/transactional-emails" \
  --header "Authorization: Bearer $SAASCO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "accounts@yourdomain.com",
    "to": "you@example.com",
    "subject": "Sample receipt for order 123",
    "html": "<p>This is a sample receipt for $25.00 USD for order 123.</p>",
    "text": "This is a sample receipt for $25.00 USD for order 123.",
    "category": "receipt",
    "idempotencyKey": "setup-receipt-order-123"
  }'
```

Save the `id` from the response. It identifies the send after the provider accepts it. Choose a new `idempotencyKey` for each new email. Reuse the same key and identical request when retrying one send.

Use the optional `category` to label related sends so you can find them in **Email Marketing → Transactional Emails**. For example, set `category` to `Password Reset` on every reset email. If someone reports a missing reset link, search for `Password Reset` and check their send’s status. The label appears in the **Category** column and can contain spaces and capital letters, up to 100 characters.

## 3. Confirm delivery

In your project, open **Email Marketing → Transactional Emails**. Search for `Sample receipt for order 123`, open the row, and check the event timeline and your inbox. An API response with an ID confirms provider acceptance. Look for **Delivered** to confirm delivery. Project admins can also click **View email body** for a read-only preview. Open and click events depend on the domain’s tracking settings.

To check the send from your backend or agent, set `SAASCO_EMAIL_ID` to the returned `id` and fetch the same record.

```bash
curl --fail-with-body --silent --show-error \
  "https://www.saasco.com/api/v2/projects/$SAASCO_PROJECT_ID/transactional-emails/$SAASCO_EMAIL_ID" \
  --header "Authorization: Bearer $SAASCO_API_KEY"
```

## 4. Connect your application

Start with one event your backend already handles, such as a successful payment.

1. Render `subject`, `html`, and optional `text` using the data from your backend event. Use the recipient associated with that event, such as the customer on a paid order.
2. Call the send endpoint from your existing backend handler or job. Give each intended email a stable `idempotencyKey`, such as `receipt:payment_123`. Preserve the key and the rendered payload when retrying. If Saasco reports a conflict, check the original send and resolve the discrepancy before sending again.
3. Trigger the event with sample data for an account you control. Confirm that exactly one send appears in your project’s log and check your inbox. Use a single sending path for each event so customers receive one email.

## Examples of emails to set up

| When this happens                                                          | What to send                                                                                                           |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| Someone verifies an account, requests a reset, or signs in on a new device | The verification or reset instructions, or a security alert with the details the user needs to recognize the activity. |
| A payment succeeds, a refund is issued, or a subscription changes          | The amount and currency, the relevant reference, and what happens next.                                                |
| An order is placed, shipped, or cancelled                                  | The order reference and the confirmed details for that stage, such as a tracking link when the order ships.            |
| Someone books an appointment or gets an update on a support request        | The time and location, or the request status and where to follow up.                                                   |

Keep discounts, product recommendations, and abandoned-cart reminders in marketing campaigns. For more examples, see [Klaviyo’s guide to transactional email types](https://www.klaviyo.com/blog/transactional-email).

## API reference

- [Send a transactional email](/docs/transactional-emails/send-transactional-email)
- [List sends and filtered stats](/docs/transactional-emails/list-transactional-emails)
- [Get one send](/docs/transactional-emails/get-transactional-email)
