[codex] Add 508 members newsletter sync

.env.example

@@ -242,10 +242,25 @@ EMAIL_RESUME_ALLOWED_EXTENSIONS=pdf,doc,docx
 EMAIL_RESUME_MAX_FILE_SIZE_MB=10
 EMAIL_REQUIRE_SENDER_AUTH_HEADERS=true
 
-# Migadu mailbox automation (required for /create-mailbox command)
-MIGADU_API_USER=your_migadu_api_user
-MIGADU_API_KEY=your_migadu_api_key
-MIGADU_MAILBOX_DOMAIN=508.dev
+# Migadu mailbox automation settings are dashboard-managed in normal deployments.
+# Set non-empty env values only when you intentionally want env to lock dashboard edits.
+# MIGADU_API_USER=your_migadu_api_user
+# MIGADU_API_KEY=your_migadu_api_key
+# MIGADU_MAILBOX_DOMAIN=508.dev
+
+# Newsletter sync settings are dashboard-managed in normal deployments.
+# Set non-empty env values only when you intentionally want env to lock dashboard edits.
+# BREVO_API_KEY=
+# BREVO_API_BASE_URL=https://api.brevo.com/v3
+# BREVO_API_TIMEOUT_SECONDS=20.0
+# BREVO_508_MEMBERS_NEWSLETTER_LIST_ID=4
+# BREVO_508_MEMBERS_NEWSLETTER_LIST_NAME="508 members"
+# KEILA_API_KEY=
+# KEILA_API_BASE_URL=https://app.keila.io
+# KEILA_API_TIMEOUT_SECONDS=20.0
+# NEWSLETTER_SYNC_ENABLED=true
+# NEWSLETTER_SYNC_INTERVAL_SECONDS=604800
+# NEWSLETTER_SYNC_EXCLUDED_MAILBOXES=system,service-account
 
 # EspoCRM (required for worker integration)
 ESPO_API_KEY=your_key_here

ENVIRONMENT.md

@@ -173,6 +173,20 @@ current precedence rules.
 
 - `Required for /create-mailbox and /create-user-accounts`: `MIGADU_API_USER`, `MIGADU_API_KEY`
 - `Optional`: `MIGADU_MAILBOX_DOMAIN` (default: `508.dev`)
+- Newsletter sync settings are normally set from the admin dashboard configuration page. A non-empty env or `.env` value locks the matching dashboard field.
+- `Optional for Brevo newsletter sync`: `BREVO_API_KEY`
+- `Optional`: `BREVO_API_BASE_URL` (default: `https://api.brevo.com/v3`)
+- `Optional`: `BREVO_API_TIMEOUT_SECONDS` (default: `20.0`)
+- `Optional for Brevo newsletter sync`: `BREVO_508_MEMBERS_NEWSLETTER_LIST_ID` (explicit Brevo list ID override; use `4` for the 508 members list when setting it directly)
+- `Optional`: `BREVO_508_MEMBERS_NEWSLETTER_LIST_NAME` (default: `508 members`; used to look up the list ID when the explicit ID is unset)
+- `Optional for Keila contact sync`: `KEILA_API_KEY`
+- `Optional`: `KEILA_API_BASE_URL` (default: `https://app.keila.io`)
+- `Optional`: `KEILA_API_TIMEOUT_SECONDS` (default: `20.0`)
+- `Optional`: `NEWSLETTER_SYNC_ENABLED` (default: `true`)
+- `Optional`: `NEWSLETTER_SYNC_INTERVAL_SECONDS` (default: `604800`, one week)
+- `Optional`: `NEWSLETTER_SYNC_EXCLUDED_MAILBOXES` (comma-separated mailbox local-parts or full addresses to skip during Migadu resync)
+- Note: mailbox and backup email subscription to configured newsletter tools is best effort. Failures are reported as warnings and do not block mailbox or account creation.
+- Note: the periodic sync uses Migadu mailboxes and password recovery emails as the source of truth for `@508.dev`. When CRM is configured, it only syncs mailboxes that match a CRM contact; it also skips configured excluded mailboxes and does not re-add provider-suppressed contacts.
 
 ## Authentik SSO Provisioning