Skip to main content

Configuration

Copy .env.example to .env. Names and defaults below match config/settings.py.

Production (DEBUG=false) refuses to boot without:

  • SECRET_KEY
  • IDENTITY_ISSUER and IDENTITY_AUDIENCE
  • IDENTITY_JWKS, IDENTITY_JWKS_FILE, IDENTITY_JWKS_URL, or IDENTITY_SERVICE_URL (pin the JWKS or set a fetch URL; localhost is not assumed when DEBUG=false)
  • POSTGRES_DATABASE_URL
  • REDIS_URL (rate limits and the scheduled jobs)
  • EMAIL_CREDENTIALS_KEY, EMAIL_VARIABLES_KEY, EMAIL_HASH_PEPPER

Generate the env​

python manage.py generate_env --host email.example.com prints every production setting with a fresh SECRET_KEY, EMAIL_CREDENTIALS_KEY, EMAIL_VARIABLES_KEY and EMAIL_HASH_PEPPER. It runs with no env, database or Redis. Replace each change-me value. Add --optional to also list the optional settings with their defaults. The output holds secrets, so store it in a secret manager and never commit it.

.env.example is generated from config/env_registry.py with python manage.py generate_env --example > .env.example. A test fails when the registry, the code, this page or .env.example drift apart.

With DEBUG=false, a SECRET_KEY shorter than 50 characters or a placeholder also stops startup. Errors name the variable and never print its value. The container runs manage.py check before migrations when DEBUG=false, and the check also refuses a key that starts with django-insecure-.

Secrets​

Generate SECRET_KEY with:

python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())"

Generate each mail secret with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

EMAIL_CREDENTIALS_KEY encrypts provider credentials. EMAIL_VARIABLES_KEY encrypts template variables until the provider accepts the message. EMAIL_HASH_PEPPER is the HMAC secret for recipient addresses. The Fernet command is the right generator for all three.

When DEBUG=true, those three are derived from SECRET_KEY if you leave them empty. Do not use that derivation in production.

Database and Redis​

VariableDefaultRole
POSTGRES_DATABASE_URLemptyPostgres URL. Required when DEBUG=false. Empty uses SQLite (SQLITE_PATH, default db.sqlite3, /app/data/db.sqlite3 in the image)
POSTGRES_SSL_REQUIREtrue when DEBUG=false, otherwise falseSet false for an internal Postgres that does not speak TLS
REDIS_URLemptyShared cache and the default Celery broker. Required when DEBUG=false. Compose sets redis://redis:6379/0
CELERY_BROKER_URLREDIS_URLOptional separate Redis for the scheduled jobs

Compose starts Redis. It does not start Postgres.

First superuser​

With DEBUG=true, an empty database shows a one-time form on /. In production, leave SETUP_TOKEN empty and create the first superuser with:

uv run python manage.py createsuperuser

The web form stays closed when DEBUG=false and SETUP_TOKEN is empty. Set SETUP_TOKEN only when you need that form once, then open /?setup_token=your_setup_token_here.

Identity (admin JWTs)​

Pin a JSON Web Key Set (JWKS) with IDENTITY_JWKS_FILE or IDENTITY_JWKS in production when the container cannot reach identity-service at runtime. Otherwise set IDENTITY_SERVICE_URL or IDENTITY_JWKS_URL and keys are fetched on demand (cached, short HTTP timeout). Update a pinned document after identity-service rotates signing keys.

VariableDefaultRole
IDENTITY_JWKS_FILEemptyPath to a JWKS file. Wins over IDENTITY_JWKS
IDENTITY_JWKSemptyPinned JWKS JSON when no file is set. Preferred in production
IDENTITY_SERVICE_URLhttp://localhost:8001 when DEBUG=true, otherwise emptyidentity-service base URL. JWKS is {url}/.well-known/jwks.json when no document is pinned. Broadcasts also call {url}/api/v1/users/audience. In Shellui dev Compose use http://identity:8000
IDENTITY_JWKS_URLderived, or http://localhost:8001/.well-known/jwks.json when DEBUG=trueFetch URL when no document is pinned. Ignored for verification when a document is set. In Shellui dev Compose use http://identity:8000/.well-known/jwks.json
IDENTITY_ISSUERemptyRequired when DEBUG=false. Match identity JWT_ISSUER
IDENTITY_AUDIENCEemptyRequired when DEBUG=false. Match identity JWT_AUDIENCE, typically shellui
JWT_HS256_FALLBACK_SECRETemptyLocal only, when identity is in DEBUG with HS256. Refused when DEBUG=false unless ALLOW_JWT_HS256_FALLBACK is set
JWT_PRIVATE_KEYemptyOptional. RS256 private key for MCP internal assertions to Identity (production fleets use the same key as identity-service)
JWT_KEY_IDemptyOptional kid for MCP service assertions when JWT_PRIVATE_KEY is set
JWKS_CACHE_TTL900Seconds to cache a fetched JWKS document. Unused for a pinned document
JWKS_TIMEOUT15Seconds for one JWKS HTTP call
JWKS_RETRIES2Extra attempts after a timeout or HTTP 5xx. HTTP 4xx is not retried
EMAIL_SERVICE_ISSUERemptyPublic origin of this service, the iss of its internal MCP assertions to Identity. Set the same EMAIL_SERVICE_ISSUER on Identity. Unset: MCP calls to Identity fail closed
EMAIL_SERVICE_SIGNING_KEYemptyRSA private key (PEM, 2048 bits or more) that signs internal MCP assertions (RS256). Public key served at /.well-known/jwks.json. Never log or commit it
EMAIL_SERVICE_SIGNING_KEY_FILEemptyPath to that PEM instead of the variable. Relative paths are from the repository root. Wins over EMAIL_SERVICE_SIGNING_KEY
JWT_ALGORITHMSRS256Accepted algorithms

Callers​

These variables live on identity-service, storage-service, and hosting-service, not on email-service.

VariableDefaultRole
EMAIL_SERVICE_URLhttps://email.shellui.comOrigin only. Callers append /api/v1/send or /api/v1/events. Local Compose is http://localhost:8004
EMAIL_SERVICE_API_KEYemptyThe esk_ key. Sent as Authorization: Bearer
EMAIL_SERVICE_ALLOW_PRIVATEfalsestorage-service and hosting-service only. Allow a URL that resolves to a private or loopback address. Set it for localhost or host.docker.internal. identity-service does not have this setting

identity-service also has EMAIL_SERVICE_TIMEOUT_SECONDS (default 5), EMAIL_SERVICE_SEND_ATTEMPTS (default 3), and EMAIL_SERVICE_RETRY_MAX_SLEEP_SECONDS (default 1) for direct sends. Event posts use the caller's webhook outbox.

Addresses​

VariableDefaultRole
EMAIL_SERVICE_PORT8004Host port for Docker Compose. The container listens on 8000
PUBLIC_BASE_URLhttps://email.shellui.comUnsubscribe links and the public origin
EMAIL_PUBLIC_URLPUBLIC_BASE_URLLibrary images and fonts load from {EMAIL_PUBLIC_URL}/static/library/
DEFAULT_FROM_EMAILno-reply@shellui.comAuth and transactional fallback
DEFAULT_FROM_NAMEShelluiDisplay name
BULK_FROM_EMAILnews@news.shellui.comBroadcast sender for companies in EMAIL_PLATFORM_COMPANY_IDS that have no Bulk From
BULK_FROM_NAMEShelluiDisplay name for BULK_FROM_EMAIL
EMAIL_AUTH_LINK_HOSTSid.shellui.com, plus localhost and 127.0.0.1 when DEBUG=truePlatform hostnames allowed in every company's auth mail. Company application domains and Allowed link hosts are added per company. DEBUG=false drops localhost, 127.0.0.1, and ::1
EMAIL_PLATFORM_COMPANY_IDSemptyComma-separated company ids that may use the platform From for non-auth mail
EMAIL_ALLOW_COMPANY_SMTPfalseAllow a company to store an SMTP relay
ALLOWED_HOSTSlocalhost,127.0.0.1Django host header allowlist
CSRF_TRUSTED_ORIGINSemptyOrigins trusted for Django admin CSRF

email.shellui.com is the API host. Mail is not sent from that domain.

Provider fallback​

VariableDefaultRole
EMAIL_FALLBACK_PROVIDERnoneOff by default. resend, ses or smtp turns it on and needs that provider's keys
RESEND_API_KEYemptyPlatform Resend key, only for EMAIL_FALLBACK_PROVIDER=resend. Broadcasts need Full access
SES_ACCESS_KEY_IDemptyPlatform SES access key, for EMAIL_FALLBACK_PROVIDER=ses
SES_SECRET_ACCESS_KEYemptyPlatform SES secret key
SES_REGIONeu-central-2Platform SES region
SES_CONFIGURATION_SETemptyOptional SES configuration set
EMAIL_FALLBACK_COMPANY_DAILY_LIMIT50Fallback mail per company per UTC day. 0 means no limit
EMAIL_FALLBACK_GLOBAL_DAILY_LIMIT500Fallback mail across all companies per UTC day. 0 means no limit
EMAIL_FALLBACK_RECIPIENT_HOURLY_LIMIT5Fallback mail per recipient per company per hour
RESEND_WEBHOOK_SECRETemptySvix secret for the platform Resend account
EMAIL_HOSTemptyPlatform SMTP host. Not gated by EMAIL_ALLOW_COMPANY_SMTP
EMAIL_PORT587Platform SMTP port
EMAIL_HOST_USERemptyPlatform SMTP username
EMAIL_HOST_PASSWORDemptyPlatform SMTP password
EMAIL_USE_TLStrueSTARTTLS
EMAIL_USE_SSLfalseImplicit TLS
EMAIL_SMTP_VERIFY_CERTtrueVerify the EMAIL_HOST certificate and hostname on STARTTLS and implicit TLS. Set false only for a private relay with a self-signed certificate; a warning is logged on each send. Company SMTP relays are always verified
EMAIL_ALLOW_FAKE_PROVIDERtrue when DEBUG=trueTest double. Off in production unless set

When DEBUG=false and the chosen fallback has no credentials, manage.py check warns (email.W001) and the service still starts. Auth mail for companies without their own provider then fails with provider_not_configured. The warning never prints key values. With none, no provider key is needed. Companies in EMAIL_PLATFORM_COMPANY_IDS without their own provider need a fallback configured, otherwise their mail, newsletters and broadcasts fail with provider_not_configured (manage.py check warns with email.W002).

Rate limits and retention​

VariableDefaultRole
EMAIL_AUTH_DEFAULT_TTL_SECONDS120Magic-link TTL when the caller omits ttl_seconds
EMAIL_AUTH_MAX_TTL_SECONDS300Cap on ttl_seconds
EMAIL_RECIPIENT_AUTH_LIMIT5Auth messages per recipient per company
EMAIL_RECIPIENT_AUTH_WINDOW_SECONDS600Window for that cap
EMAIL_COMPANY_AUTH_LIMIT30Auth messages per company
EMAIL_COMPANY_AUTH_WINDOW_SECONDS60Window for the company auth cap
EMAIL_COMPANY_TRANSACTIONAL_PER_HOUR1000Transactional messages per company per hour
EMAIL_MESSAGE_RETENTION_DAYS30Message rows deleted by purge_expired_data
EMAIL_IDEMPOTENCY_HOURS24How long a repeated idempotency_key replays
EMAIL_MAX_RECIPIENTS50Recipients on one /send
EMAIL_MAX_BATCH_ITEMS500Items on one /send/batch
EMAIL_SEND_LEASE_SECONDS120How long a worker may hold a row mid-send
EMAIL_DELIVER_SYNCfalseDeliver inside the request. Leave false outside tests
EVENT_LOG_RETENTION_DAYS7Event log and finished webhook deliveries

Broadcasts​

VariableDefaultRole
EMAIL_BROADCAST_MAX_RECIPIENTS10000Largest audience one broadcast may have. Also the CSV import cap
EMAIL_RESEND_BROADCAST_RPS4Resend calls per second while preparing a broadcast. Resend allows 10 per team, shared with every other call on the key
EMAIL_BROADCAST_STEP_SECONDS20Time one worker pass spends on broadcasts before it returns to messages

See Broadcasts.

Newsletters​

VariableDefaultRole
EMAIL_NEWSLETTER_IP_PER_HOUR10Public sign-ups per IP per hour
EMAIL_NEWSLETTER_ADDRESS_PER_DAY3Confirmation emails per address and list per day
EMAIL_NEWSLETTER_LIST_PER_HOUR500Public sign-ups per list per hour
EMAIL_NEWSLETTER_RESEND_MINUTES10Minimum wait before a pending address gets another confirmation email
EMAIL_NEWSLETTER_CONFIRM_HOURS48How long a confirmation link works
EMAIL_NEWSLETTER_PENDING_DAYS7Unconfirmed sign-ups are deleted, and addresses of unsubscribed people cleared, after this many days
EMAIL_CLIENT_IP_HEADERX-Forwarded-ForHeader carrying the visitor IP for the public sign-up rate limit. The default fits Coolify, whose Traefik proxy appends the visitor IP. Use a header your proxy sets, for example X-Real-IP or CF-Connecting-IP. Set it to an empty value (EMAIL_CLIENT_IP_HEADER=) to use the connection address (REMOTE_ADDR), for example when the service is reached without a proxy. A missing header or a value that is not an IP also falls back to REMOTE_ADDR
EMAIL_CLIENT_IP_TRUSTED_PROXIES1Only with X-Forwarded-For: the number of proxies that append to it. The visitor IP is read that many entries from the right, because the left side is set by the visitor
EMAIL_TURNSTILE_VERIFY_URLhttps://challenges.cloudflare.com/turnstile/v0/siteverifyTurnstile siteverify endpoint

See Newsletters. Addresses are read as IPv4 or IPv6, with or without a port (203.0.113.9:8080, [2001:db8::1]:443); IPv4-mapped IPv6 counts as IPv4. The per-IP limit counts IPv4 per address and IPv6 per /64.

Composing​

VariableDefaultRole
EMAIL_NODE_BINARYnodeNode used to run renderer/compose.mjs on every save
EMAIL_COMPOSE_TIMEOUT_SECONDS60A compose that runs longer fails with 503 renderer_unavailable
EMAIL_MAX_DOCUMENT_BYTES524288Largest editor document, as JSON (too_large above it)
EMAIL_MAX_VARIABLES_BYTES8192Largest variables object, as JSON

HTTP and process​

VariableDefaultRole
DEBUGfalseLocal stacks set true in .env.example
LOG_LEVELDEBUG when DEBUG=true, otherwise INFORoot log level
DJANGO_ADMIN_ENABLEDtrueDjango admin at /admin/
CORS_ALLOW_ALL_ORIGINStrue when DEBUG=true, otherwise falseProduction stays off unless you set the variable
CORS_ALLOW_CREDENTIALSfalseStartup fails if this is true together with allow-all
CORS_ALLOWED_ORIGINSemptyExtra browser origins when allow-all is off
CORS_ALLOW_PRIVATE_NETWORKtrueChrome private-network preflight
SECURE_SSL_REDIRECTtrue when DEBUG=falseRedirect HTTP to HTTPS
SECURE_HSTS_SECONDS31536000 when DEBUG=false, otherwise 0HSTS max-age
SESSION_COOKIE_SECUREtrue when DEBUG=falseSecure flag on the session cookie. When true, the name is __Host-sessionid. The cookie has no Domain
CSRF_COOKIE_SECUREtrue when DEBUG=falseSecure flag on the CSRF cookie. The cookie is HttpOnly and has no Domain. When this flag is true, the name is __Host-csrftoken
GUNICORN_WORKERS2Gunicorn worker processes
GUNICORN_THREADS2Threads per worker
GUNICORN_TIMEOUT120Worker timeout, seconds
SCHEDULER_ENABLEDtrueRun Celery beat in this container
EMAIL_WORKERS_ENABLEDtrueRun the three lane workers in this container
CELERY_WORKER_CONCURRENCY2Threads in the scheduler process
ACTIONS_WEBHOOK_TIMEOUT_SECONDS5Outbound webhook HTTP timeout
ACTIONS_OUTBOX_MAX_ATTEMPTS8Webhook attempts
ACTIONS_WEBHOOK_ALLOW_PRIVATEfalseAllow webhook targets on private addresses. Local only
ACTIONS_WEBHOOK_SYNC_DELIVERYfalseDeliver webhooks inside the request. Leave false outside tests
SENTRY_DSNemptyOptional error reporting
SENTRY_ENVIRONMENTdevelopment or production from DEBUGSentry environment name
SENTRY_TRACES_SAMPLE_RATE0Trace sample rate
SENTRY_RELEASEthe project versionSentry release name
SECURE_HSTS_INCLUDE_SUBDOMAINStrue when DEBUG=falseHSTS includeSubDomains
SECURE_HSTS_PRELOADfalseHSTS preload
ACTIONS_WEBHOOK_RETRY_LEASE_SECONDS120Lease on a webhook retry row
CELERY_BEAT_SCHEDULE_FILE/tmp/celerybeat-scheduleBeat schedule file. Losing it only resets the schedule
SHELLUI_WEBSITE_URL, SHELLUI_DOCS_URL, SHELLUI_PLAYGROUND_URLshellui.com URLsLinks on the public pages
SHELLUI_EMAIL_DOCS_URL, SHELLUI_IDENTITY_DOCS_URL, SHELLUI_GITHUB_EMAIL_URLshellui.com and GitHub URLsLinks on the public pages

Health check​

GET /health/live returns 200 ok before host checks, the HTTPS redirect, sessions and the database. The Docker image runs tools/healthcheck.py against http://127.0.0.1:8000/health/live as its HEALTHCHECK, so Coolify and Docker need no extra config. It does not check Postgres or Redis. In worker mode it always passes. GET /api/v1/health stays the detailed status endpoint.

See Scheduled jobs to move workers into their own container.