Environment variables reference for AgentTeam Email

Operator-facing Docker Compose environment variables for AgentTeam Email self-hosted deployments.

This page documents the public Docker Compose environment variable contract. The Compose files map these AT_EMAIL_ADMIN_* variables into service-native container environment variables. Helm deployments use equivalent values documented in Deploy with Helm.

The default compose.yaml stack provides MongoDB, Redis, WildDuck, Haraka, ZoneMTA, and internal service URLs on the Compose network. Set the defaulted variables below only when you are changing that topology or enabling an optional integration.

Never commit secrets to version control. Every secret, token, key, and password below must be generated per environment and stored in a deployment secret manager or Kubernetes Secret, not in committed files.

Generate secret values

Use a distinct value for every secret in every environment.

Generate AT_EMAIL_ADMIN_ENCRYPT_SECRET_KEY as exactly 32 random bytes encoded with base64url:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

Generate long random tokens or passwords for session secrets, service tokens, and internal passwords:

openssl rand -hex 32

Use these commands for:

• AT_EMAIL_ADMIN_BETTER_AUTH_SECRET
• AT_EMAIL_ADMIN_CONTROL_TO_WEB_API_TOKEN
• AT_EMAIL_ADMIN_WILDDUCK_ADMIN_ACCESS_TOKEN
• AT_EMAIL_ADMIN_WILDDUCK_ACCESS_CONTROL_SECRET
• AT_EMAIL_ADMIN_MAIL_LOOP_SECRET
• AT_EMAIL_ADMIN_ZONEMTA_RELAY_PASSWORD
• AT_EMAIL_ADMIN_FEEDBACK_MAILBOX_PASSWORD
• AT_EMAIL_ADMIN_CF_WORKER_PASSWORD

Admin web app

AT_EMAIL_ADMIN_PUBLIC_HOSTNAME · string · required

Fully-qualified public URL of your AgentTeam Email deployment. The Cloudflare Worker sends inbound mail notifications to AT_EMAIL_ADMIN_PUBLIC_HOSTNAME/rpc/agent-mail/ingest/v1/{connectionPublicId}.

Example: https://mail.company.example

AT_EMAIL_ADMIN_BETTER_AUTH_SECRET · string · required

Long random string used to sign and verify authentication sessions. Generate a unique value for every environment.

Example: a-long-random-string-change-me

AT_EMAIL_ADMIN_ENCRYPT_SECRET_KEY · string · required

32 random bytes encoded as base64url. Used to encrypt sensitive data stored at rest. Generate a fresh value per environment.

Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA (replace with real random bytes)

Compose runtime defaults

These values are defaulted by the Compose files. Leave them unset unless you are pinning a release, changing local port exposure, or matching host filesystem ownership.

AT_EMAIL_ADMIN_VERSION · string

First-party AgentTeam Email image tag.

Default: latest

AT_EMAIL_ADMIN_PULL_POLICY · string

Compose image pull policy.

Default: always

AT_EMAIL_ADMIN_UID · number

Host user ID used for first-party AgentTeam Email app containers. Bundled third-party data and mail services use their image-defined runtime users.

Default: 1000

AT_EMAIL_ADMIN_GID · number

Host group ID used for first-party AgentTeam Email app containers. Bundled third-party data and mail services use their image-defined runtime groups.

Default: 1000

AT_EMAIL_ADMIN_FRONTEND_PORT · number

Host port published for the web server.

Default: 23100

AT_EMAIL_ADMIN_DATABASE_MAX_POOL_SIZE · number

Maximum MongoDB connection pool size for the admin web app.

Default: 8

AT_EMAIL_ADMIN_TMP_DIR · string

Temporary directory used by the admin web app.

Default: /tmp/agentteam-email

Logging controls

The web server and mail-control-service emit operational info/error logs to container stdout/stderr by default. Leave these unset for normal production.

AT_EMAIL_ADMIN_WEB_SERVER_DEBUG · string

Passed to the web server as the DEBUG namespace pattern. Use this to enable detailed server-side diagnostics, including comma-separated namespace patterns such as app:* or app:*,api:backend.

Default: unset

Example: app:*

AT_EMAIL_ADMIN_WEB_SERVER_DEBUG_HIDE_DATE · boolean

Passed to the web server as DEBUG_HIDE_DATE. Compose defaults this to 1 so container log timestamps remain the primary timestamp when AT_EMAIL_ADMIN_WEB_SERVER_DEBUG is enabled.

Default: 1

The mail-control-service does not require a logging environment variable; its production operational logs are emitted by default.

Databases

AgentTeam Email requires three MongoDB databases and one Redis instance. The default compose.yaml stack supplies them with bundled services. Set these variables only when using an equivalent external data-service deployment.

The bundled MongoDB deployment runs as a single-node replica set named rs0. Custom MongoDB URIs must point at a replica set because application flows use MongoDB transactions.

Even when sharing a single MongoDB server, each URI must point to a distinct logical database.

AT_EMAIL_ADMIN_APP_MONGODB_URI · string

MongoDB connection URI for the main web application database.

Example: mongodb://user:[e-mail]:27017/agentteam_email?authSource=admin&replicaSet=rs0&tls=true

AT_EMAIL_ADMIN_WILDDUCK_MONGODB_URI · string

MongoDB connection URI for the WildDuck mail server database.

Example: mongodb://user:[e-mail]:27017/wildduck?authSource=admin&replicaSet=rs0&tls=true

AT_EMAIL_ADMIN_CONTROL_MONGODB_URI · string

MongoDB connection URI for the mail-control-service operational database. This must be a dedicated database, such as agent_mail_control; it must not share collections with the WildDuck database.

Example: mongodb://user:[e-mail]:27017/agent_mail_control?authSource=admin&replicaSet=rs0&tls=true

AT_EMAIL_ADMIN_REDIS_URL · string

Redis connection URL used by the mail stack for queuing and coordination.

Example: rediss://:[e-mail]:6379/3

Cloudflare OAuth

These variables configure the admin instance’s Cloudflare OAuth app. Users connect their own Cloudflare domains from the web UI through this app.

Configure the Cloudflare OAuth client for Authorization Code with PKCE and refresh tokens. The web app requests a fixed scope set from code, including offline_access so Better Auth can store a refresh token and refresh access over time.

The required Cloudflare OAuth scopes are:

Cloudflare section	Permission	Scope
Developer Platform	Workers R2 Storage Read	workers-r2.read
Developer Platform	Workers R2 Storage Write	workers-r2.write
Developer Platform	Workers Scripts Read	workers-scripts.read
Developer Platform	Workers Scripts Write	workers-scripts.write
Account & Billing	User Details Read	user-details.read
DNS & Zones	DNS Read	dns.read
DNS & Zones	DNS Write	dns.write
DNS & Zones	Zone Read	zone.read
Email & Messaging	Cloud Email Security Read	cloud-email-security.read
Email & Messaging	Email Routing Addresses Read	email-routing-address.read
Email & Messaging	Email Routing Addresses Write	email-routing-address.write
Email & Messaging	Email Routing Rules Read	email-routing-rule.read
Email & Messaging	Email Routing Rules Write	email-routing-rule.write
Email & Messaging	Email Routing Suppressions Read	email-routing-suppression.read
Email & Messaging	Email Security DMARC Reports Read	email-security-dmarcreports.read
Email & Messaging	Email Sending Read	email-sending.read
Email & Messaging	Email Sending Write	email-sending.write
Other	offline_access	offline_access

AT_EMAIL_ADMIN_CF_OAUTH_CLIENT_ID · string · required

Cloudflare OAuth client ID used by the web app. Configure the Cloudflare OAuth client for Authorization Code + PKCE with token endpoint auth method none.

Service-level Cloudflare Worker

Production installs that enable Cloudflare OAuth must also configure a service-level Cloudflare Worker. AgentTeam Email provisions this admin-instance Worker at startup and uses it only for authenticated POST /oauth2/token forwarding to Cloudflare’s OAuth token endpoint when server egress is challenged by Cloudflare.

This Worker belongs to the AgentTeam Email admin instance, not to a customer domain. Its Cloudflare API token, workers.dev subdomain, Worker name, and backend-to-Worker password are deployment configuration. Customer-domain Cloudflare OAuth grants must not be used to provision or authenticate this service-level Worker.

AT_EMAIL_ADMIN_CF_WORKER_ACCOUNT_ID · string · required

Cloudflare account ID that owns the service-level Cloudflare Worker.

AT_EMAIL_ADMIN_CF_WORKER_API_TOKEN · string · required

Cloudflare API token used by the web server to upload and enable the service-level Worker. The token needs account-level Workers Scripts read and write access for AT_EMAIL_ADMIN_CF_WORKER_ACCOUNT_ID.

AT_EMAIL_ADMIN_CF_WORKER_PASSWORD · string · required

Shared password used by the web server when calling the service-level Worker with Authorization: Bearer. Generate a unique high-entropy value per deployment.

AT_EMAIL_ADMIN_CF_WORKER_NAME · string · required

Cloudflare Worker script name for the service-level Worker. Set this explicitly for the deployment.

AT_EMAIL_ADMIN_CF_WORKER_SUBDOMAIN · string · required

Account workers.dev subdomain used to address the service-level Worker.

Advanced Cloudflare overrides

Leave these unset for normal Cloudflare OAuth and API access. The web app and mail-control service have built-in Cloudflare endpoint defaults.

AT_EMAIL_ADMIN_CF_API_BASE_URL · string

Cloudflare API base URL. Override only in tests or controlled non-production environments.

Default: https://api.cloudflare.com/client/v4

AT_EMAIL_ADMIN_CF_OAUTH_AUTHORIZATION_URL · string

Optional Cloudflare OAuth authorization URL override. Leave unset for normal Cloudflare OAuth.

AT_EMAIL_ADMIN_CF_OAUTH_TOKEN_URL · string

Optional Cloudflare OAuth token URL override. Leave unset for normal Cloudflare OAuth.

AT_EMAIL_ADMIN_CF_OAUTH_REVOKE_URL · string

Optional Cloudflare OAuth token revocation URL override. Leave unset for normal Cloudflare OAuth.

AT_EMAIL_ADMIN_CF_OAUTH_ISSUER · string

Optional Cloudflare OAuth issuer override.

Admin R2 archive bucket

AgentTeam Email archives mail to a Cloudflare R2 bucket owned by the admin instance. The archive client uses R2’s S3-compatible endpoint, and Worker provisioning uses Cloudflare R2 temporary credentials.

AT_EMAIL_ADMIN_R2_ACCOUNT_ID · string · required

Cloudflare account ID that owns the archive bucket.

Example: example-cloudflare-account-id

AT_EMAIL_ADMIN_R2_API_TOKEN · string · required

Cloudflare token used by mail-control only to issue temporary R2 credentials for Workers. This token must not be used for user-domain Worker deployment, Email Routing, DNS, or outbound Cloudflare Email Sending.

Example: example-r2-api-token

AT_EMAIL_ADMIN_R2_ENDPOINT · string · required

Cloudflare R2 S3-compatible endpoint URL.

Example: https://example-account-id.r2.cloudflarestorage.com

AT_EMAIL_ADMIN_R2_REGION · string

Storage region identifier. Compose and Helm default this to auto for Cloudflare R2.

Default: auto

AT_EMAIL_ADMIN_R2_BUCKET · string · required

Bucket name for the mail archive.

Example: agent-mail-archive

AT_EMAIL_ADMIN_R2_ACCESS_KEY_ID · string · required

R2 S3-compatible access key ID for archive storage.

Example: example-r2-access-key-id

AT_EMAIL_ADMIN_R2_SECRET_ACCESS_KEY · string · required

R2 S3-compatible secret access key for archive storage.

Example: example-r2-secret-access-key

Internal service credentials

These variables configure server-side service authentication. They are not browser-visible and are not user-domain credentials.

AT_EMAIL_ADMIN_CONTROL_TO_WEB_API_TOKEN · string · required

Authentication token used by mail-control-service when it calls web-server internal endpoints, including the startup runtime projection snapshot and Cloudflare raw-send callback.

AT_EMAIL_ADMIN_WILDDUCK_ADMIN_ACCESS_TOKEN · string · required

Admin access token for the WildDuck API. Used for mailbox provisioning and message delivery operations.

AT_EMAIL_ADMIN_WILDDUCK_ACCESS_CONTROL_SECRET · string · required

Shared secret for WildDuck access-control API calls.

AT_EMAIL_ADMIN_MAIL_LOOP_SECRET · string · required

Shared secret used to detect and suppress mail loop conditions between internal services.

AT_EMAIL_ADMIN_ZONEMTA_RELAY_PASSWORD · string · required

Password used by ZoneMTA to authenticate with the internal SMTP relay.

AT_EMAIL_ADMIN_FEEDBACK_MAILBOX_PASSWORD · string · required

Password for the service-owned feedback mailbox that receives bounce and DSN notifications.

Advanced internal topology overrides

Leave these unset for the default Compose network. Set them only when the service names, ports, or runtime topology differ from the bundled Compose stack.

AT_EMAIL_ADMIN_WILDDUCK_API_BASE_URL · string

WildDuck API base URL used by the web server and mail-control-service.

Default: http://wildduck:8080

AT_EMAIL_ADMIN_WILDDUCK_IMAP_ADDRESS · string

WildDuck IMAP address used by generated domain runtime configuration.

Default: wildduck:10143

AT_EMAIL_ADMIN_HARAKA_SMTP_ADDRESS · string

Haraka SMTP address used by generated domain runtime configuration.

Default: haraka:10025

AT_EMAIL_ADMIN_ZONEMTA_DSN_ADDRESS · string

ZoneMTA DSN listener address used by generated domain runtime configuration.

Default: zonemta:2526

AT_EMAIL_ADMIN_CONTROL_TO_WEB_API_BASE_URL · string

Internal web-server base URL used by mail-control-service for web-owned runtime projection and Cloudflare raw-send callbacks.

Default: http://atemail-web-server:4321

Optional transactional SMTP

These variables configure admin-instance transactional email. They do not configure user-domain sending or receiving.

AT_EMAIL_ADMIN_SMTP_ADDRESS · string

SMTP host for transactional email.

AT_EMAIL_ADMIN_SMTP_PORT · number

SMTP port.

Default: 1025

AT_EMAIL_ADMIN_SMTP_SECURE_TLS · boolean

Set to true when the SMTP provider requires TLS.

Default: false

AT_EMAIL_ADMIN_SMTP_USERNAME · string

SMTP username.

AT_EMAIL_ADMIN_SMTP_PASSWORD · string

SMTP password.

AT_EMAIL_ADMIN_SMTP_FROM_EMAIL · string

Default From address for transactional email.

AT_EMAIL_ADMIN_SMTP_REPLY_TO_EMAIL · string

Optional Reply-To address.

AT_EMAIL_ADMIN_SMTP_SEND_AS_EMAIL · string

Optional SMTP envelope sender.

Optional admin sign-in providers

These variables configure optional identity providers for the admin web app. Leave them unset to disable the provider.

AT_EMAIL_ADMIN_GOOGLE_CLIENT_ID · string

Google OAuth client ID mapped into the web app as PUBLIC_GOOGLE_CLIENT_ID.

AT_EMAIL_ADMIN_GOOGLE_CLIENT_SECRET · string

Google OAuth client secret used only by the web server.

AT_EMAIL_ADMIN_LINKEDIN_CLIENT_ID · string

LinkedIn OAuth client ID mapped into the web app as PUBLIC_LINKEDIN_CLIENT_ID.

AT_EMAIL_ADMIN_LINKEDIN_CLIENT_SECRET · string

LinkedIn OAuth client secret used only by the web server.

Optional Stripe integration

AT_EMAIL_ADMIN_STRIPE_PUBLISHABLE_KEY · string

Stripe publishable key for browser-visible Stripe flows.

AT_EMAIL_ADMIN_STRIPE_SECRET_KEY · string

Stripe secret key used only by the web server.

Optional agent trial policy

Agent trials are disabled unless AT_EMAIL_ADMIN_TRIAL_ENABLED=true.

AT_EMAIL_ADMIN_TRIAL_ENABLED · boolean

Enables the agent trial admission flow.

Default: false

AT_EMAIL_ADMIN_TRIAL_ORGANIZATION_ID · string

Organization ID used for trial mailbox ownership.

AT_EMAIL_ADMIN_TRIAL_DOMAIN · string

Domain used for trial mailbox addresses.

AT_EMAIL_ADMIN_TRIAL_ADMISSION_TOKEN · string

Admission token required by trial agent clients.

AT_EMAIL_ADMIN_TRIAL_CAPABILITIES · string

Comma-separated capability list granted to trial agents.

AT_EMAIL_ADMIN_TRIAL_CLAIM_INTENT_TTL_SECONDS · number

Claim intent lifetime in seconds.

Default: 86400

AT_EMAIL_ADMIN_TRIAL_DAILY_SEND_LIMIT · number

Daily send limit for a trial mailbox.

Default: 10

AT_EMAIL_ADMIN_TRIAL_MAILBOX_LIFETIME_SECONDS · number

Lifetime of a trial mailbox in seconds.

Default: 604800

AT_EMAIL_ADMIN_TRIAL_MAILBOX_LOCAL_PREFIX · string

Local-part prefix used when creating trial mailbox addresses.

Default: trial

AT_EMAIL_ADMIN_TRIAL_MAX_ACTIVE · number

Maximum active trial mailboxes.

Default: 25

AT_EMAIL_ADMIN_TRIAL_TOTAL_SEND_LIMIT · number

Total send limit for a trial mailbox.

Default: 50

Worker ingest

The Cloudflare Worker sends a Standard Webhooks-signed HTTP notification to the web server after writing each inbound message to R2.

The Worker ingest URL is derived automatically from AT_EMAIL_ADMIN_PUBLIC_HOSTNAME as AT_EMAIL_ADMIN_PUBLIC_HOSTNAME/rpc/agent-mail/ingest/v1/{connectionPublicId}. Self-host operators do not set a separate global ingest URL or webhook signing secret. Backend provisioning stores deployment-owned Worker secrets and supplies the Worker bindings AGENTTEAM_INGEST_URL and AGENTTEAM_WORKER_HMAC_SECRET.

Docker Compose specific

These variables are used only by the Docker Compose deployment and have no effect in Kubernetes or other runtimes.

AT_EMAIL_ADMIN_VERSION · string

Container image tag to pull for all AgentTeam Email services.

Example: latest

AT_EMAIL_ADMIN_PULL_POLICY · string

Docker image pull policy. Corresponds to the Compose pull_policy option.

Example: always

AT_EMAIL_ADMIN_UID · number

UID that first-party AgentTeam Email app containers run as. Bundled third-party containers keep their image-defined users.

Example: 1000

AT_EMAIL_ADMIN_GID · number

GID that first-party AgentTeam Email app containers run as. Bundled third-party containers keep their image-defined groups.

Example: 1000

AT_EMAIL_ADMIN_FRONTEND_PORT · number

Host port to bind for the web application in Docker Compose. Does not affect in-container listen addresses.

Example: 23100