berrypod/docs/plans/email-settings.md

Email settings: admin UI with multi-adapter support

Status: Planned

Depends on: setup-auto-confirm.md (provides email_configured?/0 and warning banner)

Context

After the setup wizard auto-confirm work, SMTP is configurable via env vars only. Self-hosted users shouldn't need to restart the server or touch env vars to configure email. This plan adds an admin settings page for email delivery with support for popular Swoosh adapters, stored in the Settings table with encrypted secrets.

Design

Precedence chain

Env vars (SMTP_HOST etc.) > DB settings > Local adapter (dev default)

If SMTP_HOST is set, env vars win — the admin UI shows the config as read-only with a note that it's controlled by environment variables. If no env vars, the admin can configure everything from the UI. If nothing is configured, falls back to Swoosh.Adapters.Local.

Supported adapters

Start with the popular ones that cover 95%+ of use cases. Each has a simple config shape:

Adapter	Module	Fields
SMTP	Swoosh.Adapters.SMTP	relay (string), port (integer), username (string), password (secret)
Postmark	Swoosh.Adapters.Postmark	api_key (secret)
Resend	Swoosh.Adapters.Resend	api_key (secret)
SendGrid	Swoosh.Adapters.Sendgrid	api_key (secret)
Mailgun	Swoosh.Adapters.Mailgun	api_key (secret), domain (string)
Brevo	Swoosh.Adapters.Brevo	api_key (secret)

Adding more later is just adding an entry to the adapter registry — no code changes needed.

Adapter registry

A simple data structure defining each adapter's config shape:

defmodule Berrypod.Mailer.Adapters do
  def all do
    [
      %{
        key: "smtp",
        name: "SMTP",
        module: Swoosh.Adapters.SMTP,
        fields: [
          %{key: "relay", label: "Server host", type: :string, required: true},
          %{key: "port", label: "Port", type: :integer, default: 587},
          %{key: "username", label: "Username", type: :string},
          %{key: "password", label: "Password", type: :secret}
        ]
      },
      %{
        key: "postmark",
        name: "Postmark",
        module: Swoosh.Adapters.Postmark,
        fields: [
          %{key: "api_key", label: "API key", type: :secret, required: true}
        ]
      },
      # ... etc
    ]
  end
end

The UI renders dynamically from this registry. Secret fields use put_secret/2 and show masked hints via secret_hint/1. Non-secret fields use put_setting/3.

Storage in Settings table

Uses the existing key-value Settings table:

Key	Type	Example
email_adapter	string	"postmark"
email_relay	string	"smtp.example.com"
email_port	integer	587
email_api_key	encrypted	(encrypted via Vault)
email_password	encrypted	(encrypted via Vault)
email_username	string	"user@example.com"
email_domain	string	"mg.example.com"

All keys are prefixed with email_. Only the fields relevant to the selected adapter are written; others are cleared on adapter change.

Runtime config loading

On app startup and on settings save:

1. Read email_adapter from Settings
2. Look up adapter in registry
3. Read all config fields for that adapter from Settings
4. Build Swoosh config keyword list
5. Call Application.put_env(:berrypod, Berrypod.Mailer, config)

This is wrapped in a Berrypod.Mailer.load_config/0 function, called from:

• Application.start/2 (boot)
• The admin settings save handler (runtime update without restart)

Updating email_configured?/0

The helper from setup-auto-confirm.md already checks if the adapter is not Swoosh.Adapters.Local. No changes needed — once the admin configures an adapter via the UI, Application.get_env returns the new adapter and the function returns true.

Changes

1. Adapter registry (lib/berrypod/mailer/adapters.ex — new)

Module with all/0, get/1, field_keys/1 functions. Pure data, no side effects.

2. Config loader (lib/berrypod/mailer.ex)

Add to existing module:

• load_config/0 — reads from Settings, builds Swoosh config, calls Application.put_env/3
• env_var_configured?/0 — returns true if SMTP_HOST is set (used by UI to show read-only state)
• current_config/0 — returns the active adapter name + config for display in the UI

3. Load on boot (lib/berrypod/application.ex)

Call Mailer.load_config/0 after Repo is started (needs DB access for Settings reads and secret decryption).

4. Admin email settings page (lib/berrypod_web/live/admin/email_settings.ex — new)

LiveView at /admin/settings/email:

• Adapter dropdown (from registry)
• Dynamic form fields based on selected adapter
• Secret fields show masked hints when a value exists, clear button, new value input
• "Send test email" button — sends a test email to the admin's address
• Read-only mode when env vars are active (show values from env, disable form)
• Save persists to Settings table, calls Mailer.load_config/0 to apply immediately

5. Route (lib/berrypod_web/router.ex)

Add in the authenticated admin live_session:

live "/admin/settings/email", Admin.EmailSettings

6. Link from warning banner

Update the warning banner from setup-auto-confirm to link to /admin/settings/email: "Email delivery not configured. Configure email ->"

7. Admin nav

Add "Email" under settings in the admin sidebar, or as a tab on the existing settings page.

8. Test email function (lib/berrypod/mailer.ex)

• send_test_email/1 — sends a simple test email to the given address using current config. Returns {:ok, _} or {:error, reason}.

9. Tests

test/berrypod/mailer_test.exs (new):

• load_config/0 reads from Settings and applies to Application env
• load_config/0 with no settings keeps Local adapter
• env_var_configured?/0 checks SMTP_HOST

test/berrypod/mailer/adapters_test.exs (new):

• Registry returns all adapters
• Each adapter has required fields

test/berrypod_web/live/admin/email_settings_test.exs (new):

• Page renders adapter dropdown
• Changing adapter shows correct fields
• Saving config persists to Settings
• Secret fields show masked hints
• Read-only when env vars are set

Files to modify

File	Change
lib/berrypod/mailer/adapters.ex	New — adapter registry
lib/berrypod/mailer.ex	Add load_config/0, env_var_configured?/0, current_config/0, send_test_email/1
lib/berrypod/application.ex	Call Mailer.load_config/0 on boot
lib/berrypod_web/live/admin/email_settings.ex	New — admin settings page
lib/berrypod_web/router.ex	Add email settings route
lib/berrypod_web/components/layouts/admin.html.heex	Link banner to settings page, add nav entry
assets/css/admin/components.css	Styles for email settings form
Tests (3 new files)	Mailer, adapters, LiveView

Verification

1. mix precommit passes
2. No env vars set: admin UI at /admin/settings/email shows adapter dropdown, can configure Postmark with API key, save, email_configured?() returns true, warning banner disappears
3. With SMTP_HOST set: admin UI shows SMTP config read-only with "controlled by environment variables" note
4. "Send test email" delivers to admin's address
5. Server restart: config reloaded from DB, email still works
6. Adapter change: old config cleared, new adapter's fields shown, save applies immediately