# Environment Variables

All external integrations and deployment settings use environment variables. The canonical template is **[`.env.example`](../.env.example)** at the project root — **this document must stay in sync with that file** (same names, same order, same groupings).

**Never commit real secrets.** Copy `.env.example` to `.env.local` for local development (from Task 002 onward). All external services (MongoDB, auth, SMTP, IMAP, OpenAI, n8n, Redis) are configured only via env vars.

---

## Variable reference

| Name | Purpose | Required now? | Phase |
|------|---------|---------------|-------|
| `MONGODB_URI` | MongoDB connection string for CRM and marketing data | **yes** | Phase 1 (Task 002+) |
| `NEXTAUTH_SECRET` | Secret for signing NextAuth session tokens | **yes** | Phase 1 (Task 002+ env validation; used Task 003) |
| `NEXTAUTH_URL` | Canonical app URL for NextAuth callbacks | **yes** | Phase 1 (Task 002+ env validation; used Task 003) |
| `APP_URL` | Public base URL for emails, webhooks, absolute links | **yes** | Phase 1 (Task 002+) |
| `SMTP_HOST` | Outbound SMTP server hostname (internal sending engine) | no | Phase 5 (Task 014) |
| `SMTP_PORT` | Outbound SMTP port (e.g. 587 or 465) | no | Phase 5 (Task 014) |
| `SMTP_USER` | SMTP authentication username | no | Phase 5 (Task 014) |
| `SMTP_PASS` | SMTP authentication password | no | Phase 5 (Task 014) |
| `SMTP_FROM` | Default From address for outbound mail | no | Phase 5 (Task 014) |
| `EMAIL_SEND_BATCH_SIZE` | Max recipients sent in one synchronous batch call | no (default `20`) | Phase 5 (Task 010) |
| `EMAIL_SEND_DELAY_MS` | Delay between recipients in batch sending (ms) | no (default `1000`) | Phase 5 (Task 010) |
| `EMAIL_TRACKING_ENABLED` | Enable open pixel and tracked-link rewriting | no (default `true`) | Phase 5 (Task 010) |
| `IMAP_HOST` | Inbound IMAP server hostname (business inbox sync) | no | Phase 6 (Task 011) |
| `IMAP_PORT` | Inbound IMAP port (typically 993) | no | Phase 6 (Task 011) |
| `IMAP_USER` | IMAP mailbox username | no | Phase 6 (Task 011) |
| `IMAP_PASS` | IMAP mailbox password or app password | no | Phase 6 (Task 011) |
| `IMAP_TLS` | Enable IMAP TLS connection | no (default `true`) | Phase 6 (Task 011) |
| `IMAP_MAILBOX` | Mailbox/folder to sync from | no (default `INBOX`) | Phase 6 (Task 011) |
| `IMAP_SYNC_LIMIT` | Max fetched emails per sync run | no (default `50`) | Phase 6 (Task 011) |
| `AI_PROVIDER` | AI backend: `fallback` (default), `openai`, `gemini`, `anthropic`; overridable in DB via Settings → AI (admin) | no (default `fallback`) | Task 012 / 016 |
| `OPENAI_API_KEY` | OpenAI API key when `AI_PROVIDER=openai` | no | Task 012 |
| `OPENAI_MODEL` | OpenAI model id for classification | no (default `gpt-4o-mini`) | Task 012 |
| `GEMINI_API_KEY` | Google Gemini (placeholder provider) | no | Task 012+ |
| `GEMINI_MODEL` | Gemini model id | no | Task 012+ |
| `ANTHROPIC_API_KEY` | Anthropic API (placeholder provider) | no | Task 012+ |
| `ANTHROPIC_MODEL` | Anthropic model id | no | Task 012+ |
| `N8N_WEBHOOK_EMAIL_REPLY` | n8n webhook when inbound/reply email is processed | no | Phase 7 (Task 019) |
| `N8N_WEBHOOK_LEAD_CREATED` | n8n webhook when a lead is created | no | Phase 7 (Task 019) |
| `N8N_WEBHOOK_CAMPAIGN_CREATED` | n8n webhook when a campaign is created | no | Phase 7 (Task 019) |
| `N8N_WEBHOOK_FOLLOW_UP` | n8n webhook for follow-up automation | no | Phase 7 (Task 019) |
| `REDIS_URL` | Optional Redis for queues, rate limits, or cache | no | Optional (as needed) |
| `INITIAL_ADMIN_NAME` | Display name for first admin (bootstrap only) | no | Phase 1 (Task 003 — local setup) |
| `INITIAL_ADMIN_EMAIL` | Email for first admin (bootstrap only) | no | Phase 1 (Task 003 — local setup) |
| `INITIAL_ADMIN_PASSWORD` | Plain password for first admin; hashed on create; never logged | no | Phase 1 (Task 003 — local setup) |
| `BOOTSTRAP_SECRET` | Secret for `x-bootstrap-secret` header on `POST /api/admin/bootstrap` | no | Phase 1 (Task 003 — required to call bootstrap) |

**Required now?** — **yes** for the four core variables when running the app locally or calling server routes that use `getEnv()`. Bootstrap and initial admin vars are optional but required to create the first user via the bootstrap API.

---

## `.env.example` (mirror)

The root file lists exactly these variables (empty values). Do not add undocumented vars to `.env.example` without updating this table.

```env
# See ../.env.example for the full commented template.
MONGODB_URI=
NEXTAUTH_SECRET=
NEXTAUTH_URL=
APP_URL=
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASS=
SMTP_FROM=
EMAIL_SEND_BATCH_SIZE=20
EMAIL_SEND_DELAY_MS=1000
EMAIL_TRACKING_ENABLED=true
IMAP_HOST=
IMAP_PORT=
IMAP_USER=
IMAP_PASS=
IMAP_TLS=true
IMAP_MAILBOX=INBOX
IMAP_SYNC_LIMIT=50
AI_PROVIDER=fallback
OPENAI_API_KEY=
OPENAI_MODEL=gpt-4o-mini
GEMINI_API_KEY=
GEMINI_MODEL=
ANTHROPIC_API_KEY=
ANTHROPIC_MODEL=
N8N_WEBHOOK_EMAIL_REPLY=
N8N_WEBHOOK_LEAD_CREATED=
N8N_WEBHOOK_CAMPAIGN_CREATED=
N8N_WEBHOOK_FOLLOW_UP=
REDIS_URL=
INITIAL_ADMIN_NAME=
INITIAL_ADMIN_EMAIL=
INITIAL_ADMIN_PASSWORD=
BOOTSTRAP_SECRET=
```

---

## Runtime requirements (by milestone)

| Milestone | Variables that must be set |
|-----------|----------------------------|
| Task 002 — dev server / health | `MONGODB_URI`, `NEXTAUTH_SECRET`, `NEXTAUTH_URL`, `APP_URL` |
| Task 003 — auth | Same four (NextAuth uses auth vars) |
| Task 010 — send email | All `SMTP_*` (+ optional `EMAIL_SEND_*`, `EMAIL_TRACKING_ENABLED`) |
| Task 011 — IMAP inbox foundation | `IMAP_HOST`, `IMAP_PORT`, `IMAP_USER`, `IMAP_PASS` (+ optional `IMAP_TLS`, `IMAP_MAILBOX`, `IMAP_SYNC_LIMIT`) |
| Task 012 — AI classification (fallback) | No AI keys required (`AI_PROVIDER=fallback` or unset) |
| Task 012 — AI classification (OpenAI) | `AI_PROVIDER=openai`, `OPENAI_API_KEY` (+ optional `OPENAI_MODEL`) |
| Task 019 — n8n | Relevant `N8N_WEBHOOK_*` (optional per workflow) |

Empty webhook URLs mean skip call (local dev friendly). See [09-n8n-integration.md](./09-n8n-integration.md).

---

## Validation

- Fail fast at startup when required vars for **enabled** features are missing (implemented in Task 002+).
- Webhook URLs must use HTTPS in production.
- Rotate `NEXTAUTH_SECRET` and mail credentials per [11-security.md](./11-security.md).

---

## When adding a variable

1. Add to `.env.example` with comment.
2. Add a row to the table above.
3. Update [16-changelog.md](./16-changelog.md).
4. Update [15-cursor-rules.md](./15-cursor-rules.md) if process changes.