Add Mailpit email transport

2026-08-17 16:35:14 -04:00
parent 67ab6b78bd
commit 1853eaa963
23 changed files with 567 additions and 148 deletions
@@ -16,7 +16,7 @@ Web application and API for **beenvoice** — invoicing for freelancers and smal
 | Database    | PostgreSQL 17, Drizzle ORM                                         |
 | Auth        | better-auth (email/password, optional Authentik OIDC, Expo mobile) |
 | UI          | shadcn/ui, Tailwind CSS v4                                         |
-| Email / PDF | Resend, `@react-pdf/renderer`                                      |
+| Email / PDF | Resend or SMTP/Mailpit, `@react-pdf/renderer`                      |
 | Runtime     | Bun                                                                |

 ## Features
@@ -24,7 +24,7 @@ Web application and API for **beenvoice** — invoicing for freelancers and smal
 - Clients, businesses, invoices (line items, tax, status workflow)
 - Time clock with one running timer per user; clock-out can append invoice lines
 - Expenses, payments, recurring invoices, invoice templates
- PDF export and email delivery (Resend)
+- PDF export and email delivery (Resend in production, Mailpit locally)
 - Public invoice links (`/i/[token]`)
 - CSV import, reports, platform branding / admin settings
 - MCP API (`/api/mcp`) for automation via API keys (`bv_…`)
@@ -62,7 +62,13 @@ BETTER_AUTH_URL=http://localhost:3000
 NEXT_PUBLIC_APP_URL=http://localhost:3000
 ```

-Email and SSO are optional for local work — leave `RESEND_*` and `AUTHENTIK_*` blank unless you need them.
+SSO is optional for local work. Email defaults to Mailpit: start the development
+Compose services and open `http://localhost:8028` to inspect messages.
+
+```bash
+bun run --filter @beenvoice/web docker:up
+bun run email:preview
+```

 ### 3. Database

@@ -199,7 +205,9 @@ Use the literal strings `true` or `false` (or omit the variable). Do not rely on

 | Variable                                                             | Purpose                                                              |
 | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `RESEND_API_KEY`, `RESEND_DOMAIN`                                    | Invoice and password-reset email                                     |
+| `EMAIL_PROVIDER`, `EMAIL_FROM`                                       | Select `mailpit`, `smtp`, or `resend` and configure the sender       |
+| `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`                              | Local Mailpit or another SMTP-compatible transport                   |
+| `RESEND_API_KEY`, `RESEND_DOMAIN`, `RESEND_FROM`                     | Production Resend delivery                                           |
 | `AUTHENTIK_ISSUER`, `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET` | OIDC SSO (also set `NEXT_PUBLIC_AUTHENTIK_ENABLED=true` and rebuild) |
 | `CRON_SECRET`                                                        | Protects `/api/cron/generate-recurring`                              |
 | `DISABLE_SIGNUPS=true`                                               | Block new registrations                                              |