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, the SES inbound backstop (draining PM_SES_INBOUND_QUEUE_URL, when set), and minting the Durable Object IDs that only the Worker can mint for rows written outside it: the system identity’s mailbox, the DomainMonitor of a domain row with monitor_do_id = '' (the platform domain, and domains added with pmail domains add --local-token), the Notifier of a tenant row with notify_do_id = '' (then NotifierRequest::Init), and the SesControl object when SES is configured. 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, the nightly backup job once per UTC day when PM_BACKUP_BUCKET is set, and the new-workspace send-ramp evaluation once per UTC day (crons/signup_ramp.rs; it finds ramped Free workspaces with PM_BILLING=stripe, and ramped tenants of partners on any deployment).

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} with { "policy": { … } } deep-merges it; it needs tenants:manage, so a platform key changes any tenant’s policy and a partner key the policy of the tenants its partner’s keys created (REST API › Partners). Tenant keys and the console cannot change it. A partner key may change only some fields, and some only downwards (Who may change a field), so one partner cannot spend the shared sending reputation or the AI budget of a Cloud deployment. 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,
    "key_release": false
  },
  "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,
    "cloudflare_zones": []
  },
  "web_bot_auth": {
    "allowed": false
  },
  "domain_fallback": true
}

Who may change a field

Every policy write is checked against this table: the policy of POST /v1/tenants and of PATCH /v1/tenants/{tenant_id}. Only the fields present in the write are compared; one refused field refuses the whole write and nothing is stored. Platform keys may set every field. Tenant keys, identity keys and the console cannot write the policy at all (PATCH /v1/tenants/{tenant_id} needs tenants:manage).

• Ceiling. A lower-only field’s ceiling is the more restrictive of the deployment default (the built-in defaults above merged with PM_DEFAULT_POLICY) and the tenant’s platform ceiling, the value a platform key last set on that field, at creation or by PATCH (kept in tenants.policy_ceilings_json): min(deployment default, platform ceiling). A platform key’s null for the field removes its platform ceiling. A higher number is always the looser value, the abuse thresholds included (a higher rate makes auto-pause more lenient), and so are longer retention, more steps or seconds, and more automatic exchanges.
• Switches. For auto_reply.allowed, inbound.extract_image_text, triage.enabled and search.agentic_enabled, true is the looser value (it sends more mail or spends Workers AI). A partner key may always set false, and true only when the deployment default and the platform ceiling (if any) are both true.
• null from a partner key on a lower-only field resets it to the deployment default, so it is compared as that value: refused when a platform ceiling is lower.
• Ceilings are checked when a value is written. Changing PM_DEFAULT_POLICY later does not rewrite stored values; a platform key that wants a tenant lower sets the field.
• An identity’s send_policy.daily_cap (POST …/identities, PATCH /v1/identities/{identity_id}) may not exceed the tenant’s effective identity_daily_send_cap for any key but a platform key (403 scope_denied, details.field = "send_policy.daily_cap"), so a lower-only cap cannot be raised one identity at a time.
• quarantine.on_auth_fail: false is free, but it removes a guarantee: mail whose authentication verdict is fail or unverified is then stored as received and evented to agents with that verdict, instead of being quarantined (rules 3 and 3a of Inbound › Quarantine decision). A partner that turns it off accepts that its agents must check verdict themselves.

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.