Configuration

There are three layers:

1. Deployment configuration: the Worker’s bindings, variables and secrets, written into deploy/wrangler.toml by pmail setup and uploaded by pmail deploy.
2. Tenant policy: a JSON document per tenant, managed through the API. Defaults come from PM_DEFAULT_POLICY or the built-in defaults below.
3. CLI configuration: ~/.config/pylota-mail/config.toml on the machine that runs pmail.

Bindings

Every work queue has a dead-letter queue with a consumer (batch 100) that records items in D1 (dlq_items). That makes ten queues in all.

The Durable Object migrations (new_sqlite_classes: IdentityMailbox, DomainMonitor, JobRunner, TenantQuota, SesControl and Notifier, six classes) are part of the generated wrangler.toml and are versioned with the release (Rust workspace › Generated wrangler.toml). The generated file also turns invocation logs off and traces off in production ([observability.logs] invocation_logs = false), because invocation logs record request URLs and email recipients (Observability › Signals).

Cron triggers:

• * * * * *: address retirement, the platform-event outbox sweep, restarting jobs left queued, the state-alert evaluator, and the SES inbound backstop (draining PM_SES_INBOUND_QUEUE_URL, when set). Retrying stuck sends, transport claims and uncertain-send bookkeeping run in each mailbox’s own alarms, not in the cron.
• */15 * * * *: domain health scheduling, retention, usage roll-up, the master-key re-seal sweep, and the nightly backup job once per UTC day when PM_BACKUP_BUCKET is set.

Variables

Secrets

pmail setup generates the random ones (32 bytes from the OS CSPRNG, base64) and uploads them as Worker secrets. Without --print-secrets they go only to the Worker (through Wrangler, on stdin), never to stdout, a file or a log; with it they are printed once to stdout.

Rotating PM_KEY_PEPPER (pmail setup --rotate-pepper) invalidates every API key, so it is a break-glass action. Rotating PM_MASTER_KEY uses pmail secrets rotate-master, which uploads PM_MASTER_KEY_NEXT, waits until the Worker has re-sealed every stored value under it, then replaces PM_MASTER_KEY. No secret is ever read back from the Worker by the CLI (Security design).

Thread and link keys

The keys that sign thread tokens, signed links, search cursors and Web Bot Auth requests are not Worker secrets. The Worker generates them (32 random bytes each), stores them in D1 signing_keys sealed under PM_MASTER_KEY, and puts their key ID (kid) in everything it signs: one character for thread, link and cursor, and the RFC 7638 thumbprint of the public key for web_bot_auth. No API, CLI command or log ever returns a private key; the web_bot_auth public key is published in the key directory.

All four need a platform key with platform:ops (REST API); the CLI is pmail keys rotate thread|link|cursor|web_bot_auth. Identity signing keys are not in this table: each identity has its own, rotated through POST /v1/identities/{identity_id}/keys/rotate (Agent signing keys). Add ?revoke_previous=true (--revoke-previous) after a suspected leak: the previous kid is deleted at once instead of verifying for its window, so what it signed stops working (thread tokens fall back to header threading; open links, sign-in tokens, invitations, sessions, OAuth flows and cursors fail). Then rotate PM_MASTER_KEY.

Tenant policy

Stored per tenant. PATCH /v1/tenants/{tenant_id} (a platform key with tenants:manage) with { "policy": { … } } deep-merges it. This is the full document with defaults:

{
  "identity_daily_send_cap": 500,
  "tenant_daily_send_cap": 5000,
  "max_recipients": 10,
  "send_allowlist_only": false,
  "large_attachments": "refuse",
  "link_ttl_hours": 72,
  "ai_disclosure": { "mode": "none", "text": "This message was written with the help of an AI assistant." },
  "auto_reply": {
    "allowed": true,
    "max_automatic_exchanges": 2
  },
  "quarantine": {
    "on_auth_fail": true,
    "spam_threshold": 0.8,
    "unsolicited_otp": true
  },
  "inbound": {
    "per_sender_per_hour": 60,
    "extract_attachment_text": ["pdf", "office", "text", "html"],
    "extract_image_text": false,
    "ses_bounce_retired": true
  },
  "retention": {
    "raw_days": 90,
    "message_days": null,
    "events_days": 30
  },
  "triage": {
    "enabled": true,
    "categories": null,
    "rules": []
  },
  "search": {
    "agentic_enabled": true,
    "agentic_daily_cap": 500,
    "agentic_max_steps": 6,
    "agentic_max_seconds": 8,
    "refs_packs": ["core"],
    "custom_refs": []
  },
  "webhook_text_bytes": 16384,
  "abuse": {
    "complaint_rate_pause": 0.003,
    "bounce_rate_pause": 0.05
  },
  "domains": {
    "allow_create_zone": false
  },
  "web_bot_auth": {
    "allowed": false
  },
  "domain_fallback": true
}

CLI configuration

# ~/.config/pylota-mail/config.toml
[profiles.default]                 # the profile pmail setup and pmail login write unless --profile names another
url = "https://mail.example.com"
key = "pmk_live_…"                 # or key_command = "op read op://vault/pylota-mail/key"
identity = "bookings.acme@agents.example"   # default for mail commands
account_id = "0123456789abcdef0123456789abcdef"   # Cloudflare account ID, stored by pmail setup

[profiles.staging]
url = "https://mail-staging.example.com"
key_env = "PYLOTA_MAIL_STAGING_KEY"

Precedence, highest first: command-line flags (--url, --key, --profile, --account-id), then the environment (PYLOTA_MAIL_URL, PYLOTA_MAIL_KEY, PYLOTA_MAIL_PROFILE, CLOUDFLARE_ACCOUNT_ID), then the profile in the file. Without --profile or PYLOTA_MAIL_PROFILE, the profile is default_profile when the file sets it, else the one named default. pmail setup and pmail login write the profile named by --profile, default default; PYLOTA_MAIL_PROFILE and default_profile do not change it. The file is created with mode 0600, and pmail refuses to read it (exit 3) if its group or other users have any access to it, or if another user owns it.

The commands that use CLOUDFLARE_API_TOKEN are listed in CLI › Commands that use your Cloudflare token. The token is never stored. The account ID comes from --account-id (a global flag), else CLOUDFLARE_ACCOUNT_ID, else the profile’s account_id (written by pmail setup; not a secret), else PM_CF_ACCOUNT_ID in deploy/wrangler.toml.