Source: https://www.hype-stack.dev/docs/backend/mailing

# Mailing

Transactional email uses [Resend](https://resend.com) and React Email templates that live next to the feature that sends
them. The free template wires the Resend client; packs add the templates and call sites.

## Client

```ts
// apps/backend/src/libs/email/resend.ts
import { Resend } from "resend";

export const resend = new Resend(process.env.RESEND_API_KEY);
```

The From address is built from `RESEND_FROM_DOMAIN` (see app constants). Without `RESEND_API_KEY`, optional send paths
(billing receipts, some notification channels) skip email instead of failing the request. Auth and invitation flows that
require email will not work until the key is set.

## Environment variables

| Variable             | Purpose                          |
| -------------------- | -------------------------------- |
| `RESEND_API_KEY`     | Resend API key                   |
| `RESEND_FROM_DOMAIN` | Domain used for the From address |

## Template locations

Templates are React Email components colocated under feature modules, for example:

| Email                    | Typical path                                                           |
| ------------------------ | ---------------------------------------------------------------------- |
| Password reset / changed | `features/auth/modules/*/emails/*.tsx`                                 |
| Organization invitation  | `features/organizations/modules/send-organization-invitation/emails/`  |
| Billing receipt          | `features/billing/modules/send-receipt/emails/receipt.tsx`             |
| Admin notification       | `features/notifications/.../emails/admin-notification.tsx`             |
| Newsletter release       | `features/newsletter/lib/delivery/`, rendered from the studio's blocks |

Send sites call `resend.emails.send({ from, to, subject, react })` (or HTML) directly from the module. There is no
separate email microservice.

## Trigger points

| Flow          | When it sends                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------- |
| Auth          | Password reset, email verification (starter-dependent)                                                              |
| Organizations | Invitation email on send / resend                                                                                   |
| Billing       | Receipt after successful payment when Resend is configured                                                          |
| Notifications | Optional email channel when admins target specific users                                                            |
| Newsletter    | Paced batch sends from the `newsletter-dispatch` job, with Resend delivery events coming back over a signed webhook |

Frontend links inside emails should use the `frontendUrl()` helper so paths and query params stay typed against
`FRONTEND_URL`.

## Adding a template

1. Create a React Email component next to the module that will send it
2. Call `resend.emails.send` from that module with the component as `react`
3. Keep provider-specific HTTP details in `libs/email`
4. Document any new env needs in `.env.example`

## Related

- [Authentication](/docs/backend/authentication)
- [Organizations](/docs/backend/organizations)
- [Billing (Stripe)](/docs/packs-templates/packs/pack-billing-stripe)
- [Notifications](/docs/packs-templates/packs/pack-notifications)