Configuration
Configuration
IMAP/SMTP accounts need no central mail configuration: each account stores its own servers and credentials. The values below configure the deployment itself.
Bindings
| Binding | Required | Purpose |
|---|---|---|
DB (D1) |
Yes | Accounts, settings, IMAP sync metadata, relay archive/drafts metadata |
BUCKET (R2) |
No | Sent/draft archive for relay accounts; optional IMAP body/attachment archive |
Use exactly these names: the code reads env.DB and env.BUCKET. When BUCKET is absent, R2 is hidden in the UI.
Required secrets
| Name | Type | Purpose |
|---|---|---|
APP_PASSWORD |
Secret | Login password for the whole app |
TOKEN_ENC_KEY |
Secret | 32-byte base64 key for AES-256-GCM encryption of stored credentials |
Generate the encryption key with:
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
Changing
TOKEN_ENC_KEYmakes all stored credentials unreadable and invalidates sessions and pending OAuth states. Users must re-enter passwords and reconnect OAuth accounts.
Optional variables
| Name | Purpose |
|---|---|
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Google Drive archive for relay and IMAP accounts |
GOOGLE_MAIL_CLIENT_ID / GOOGLE_MAIL_CLIENT_SECRET |
Google OAuth for IMAP/SMTP |
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET / MICROSOFT_TENANT |
Outlook / Microsoft 365 OAuth |
RELAY_PROVIDER / RELAY_API_KEY / RELAY_API_SECRET |
Deployment-wide relay fallback |
MAILGUN_DOMAIN / MAILGUN_REGION |
Mailgun relay fallback |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY / VAPID_SUBJECT |
Web Push notifications |
CRON_SECRET |
Shared secret between Pages and the cron worker |
UPDATE_CHECK |
Set to off to stop the outbound release check |
GITHUB_TOKEN |
Optional token, only used to raise the release-check rate limit |
Relay credentials can also be entered per account in the UI and are encrypted at rest. Per-account values take precedence over the deployment fallbacks.
MICROSOFT_TENANT defaults to common for personal and work accounts.
Environment reference
| Name | Required | Purpose |
|---|---|---|
APP_PASSWORD |
Yes | App login |
TOKEN_ENC_KEY |
Yes | AES-GCM key for stored credentials |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
No | Drive archive |
GOOGLE_MAIL_CLIENT_ID / GOOGLE_MAIL_CLIENT_SECRET |
No | Google OAuth for IMAP/SMTP |
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET |
No | Outlook OAuth |
MICROSOFT_TENANT |
No | Defaults to common |
RELAY_PROVIDER |
No | Default relay fallback |
RELAY_API_KEY |
No | Default relay key fallback |
RELAY_API_SECRET |
No | Mailjet fallback secret |
MAILGUN_DOMAIN / MAILGUN_REGION |
No | Mailgun fallback |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY |
No | Web Push VAPID keys |
VAPID_SUBJECT |
No | VAPID contact (mailto:) |
CRON_SECRET |
No | Shared secret for the cron worker |
DB (D1 binding) |
Yes | Metadata |
BUCKET (R2 binding) |
No | R2 archive |
UPDATE_CHECK |
No | off disables the release check |
GITHUB_TOKEN |
No | Raises the release-check rate limit |
Deployment-wide settings in D1
Some preferences are stored in the app_settings table instead of environment variables, and are edited from the UI:
default_signature,signature_mode— shared signature or one per account.allow_remote_images— global default for remote images.metadata_retention_days,retention_stats— metadata retention window and last cleanup.- TOTP/2FA material.
update_check,update_notice_dismissed— release-check cache and dismissal.
Local environment file
For local development, .dev.vars (gitignored) holds the same values:
APP_PASSWORD=change-me
TOKEN_ENC_KEY=<32-byte base64 key>
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_MAIL_CLIENT_ID=
GOOGLE_MAIL_CLIENT_SECRET=
MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=
MICROSOFT_TENANT=common
RELAY_PROVIDER=smtp2go
RELAY_API_KEY=
OAuth
Google Drive, Google IMAP/SMTP and Microsoft OAuth each need an OAuth application and matching redirect URIs. See OAuth setup.
Signatures
signature_mode is shared (default) or per_account:
shared:default_signatureis used for every account andaccounts.signatureis ignored.per_account: every account uses its ownaccounts.signature; an empty value means no signature.