# Transactional email and delivery outbox

Adds an individual email composer and owner outbox to the shared backend email service. Automatic booking, service visit, invoice, order and chat notices use the same durable outbox.

## Install

Use the verified installer in the website container. It installs dependencies, checks checksums, and refuses to replace customer changes:

```sh
python /opt/runalio/catalog_install.py email-sending
python /opt/runalio/catalog_install.py --status
```

Review the preview and click Publish to promote backend code and pages. Production data remains separate.

To undo the last installation before publishing: `python /opt/runalio/catalog_install.py --rollback`.

## Settings

The customer enters these in Runalio, Settings → Website modules → this module (never in files or chat):

| Name | Required | Secret | Purpose |
|---|---|---|---|
| `EMAIL_PROVIDER` | yes | no | resend, postmark, sendgrid or mailgun. |
| `EMAIL_API_KEY` | yes | yes | API key of that provider. |
| `EMAIL_FROM` | yes | no | Sender address on a domain verified with the provider, e.g. hello@their-domain.com. |
| `MAILGUN_DOMAIN` | no | no | Mailgun only. |

## What the customer needs to do

1. Create an account with Resend, Postmark, SendGrid or Mailgun and verify their business sending domain.
2. Enter EMAIL_PROVIDER, EMAIL_API_KEY and EMAIL_FROM in Settings → Website modules → Email sending; Mailgun also requires MAILGUN_DOMAIN.
3. Choose Manage Email sending to compose individual transactional emails, inspect message bodies and provider acceptance, or retry queued/failed messages.

## Agent integration

Use `queueEmail(app, stableId, {to, subject, text})` from `lib/email.js`. A stable ID avoids enqueuing duplicate notices. The background job claims each row, retries failures with backoff, and marks repeated failures for owner intervention. Resend also receives a stable provider idempotency key; other providers can deliver a duplicate after an ambiguous timeout. Provider acceptance is shown as sent, and does not guarantee inbox delivery.

Preview emails remain in the preview outbox and are never sent. Inspect confirmation links in Business admin when testing newsletter opt-in. SMTP is blocked; the four supported providers use HTTPS. Use the newsletter module and the owner's email provider for consented campaigns. Use the mailbox module for receiving and replying to email.