Worker Variables
Note
For CLI deployment syntax, please refer to worker/wrangler.toml.template
Defaults and Example Values
Each table separates Required, Default / When unset, and Example. Required variables must be configured for the deployment. Other defaults describe the Worker's actual runtime behavior when the variable is unset; they are not example settings from wrangler.toml.template.
Unless an entry or its notes describe a different fallback, a Text/JSON boolean is enabled only by the boolean value true or the string "true"; an unset value is treated as false. Therefore, an unset ENABLE_* feature is disabled by default, while an unset DISABLE_* restriction does not apply. For strings, numbers, arrays, and objects, use the unset behavior documented by the individual entry.
Core Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
DOMAINS | JSON | Yes | All domains for temporary email, supports multiple domains | None | ["awsl.uk", "dreamhunter2333.xyz"] |
JWT_SECRET | Text/Secret | Yes | Secret key for signing JWTs used in login and authentication. Use a random string, e.g. generated via openssl rand -hex 32 | None | a1b2c3d4... |
ADMIN_PASSWORDS | JSON | No | Admin console passwords; admin password login is disabled when unset | [] | ["123", "456"] |
DISABLE_USER_SYSTEM | Text/JSON | No | Block user system APIs and hide user interfaces | false | true |
ENABLE_USER_CREATE_EMAIL | Text/JSON | No | Whether to allow users to create mailboxes | false | true |
ENABLE_USER_DELETE_EMAIL | Text/JSON | No | Whether to allow users to delete emails | false | true |
ENABLE_MAIL_READ_STATUS | Text/JSON | No | Enables read/unread mail state. Upgrade the database schema before enabling | false | true |
ENABLE_REDEEM_CODE | Text/JSON | No | Enables the redemption page, public redemption APIs, and Admin redemption management | false | true |
REDEEM_CODE_URL | Text | No | External URL for obtaining redemption codes | Empty; link hidden | https://example.com/redeem-codes |
`DOMAINS` and `DEFAULT_DOMAINS` must already be set up in Cloudflare
Every domain you put here (including DEFAULT_DOMAINS, USER_ROLES.domains, RANDOM_SUBDOMAIN_DOMAINS further below) must already have Cloudflare Email Routing enabled and its email DNS records provisioned. After the Worker is deployed, bind the domain's Catch-all rule to that Worker; otherwise inbound mail will never reach the Worker. See Cloudflare Email Routing for the setup steps.
Console Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
PASSWORDS | JSON | No | Website private passwords, required after configuration | []; public access | ["123", "456"] |
ADMIN_API_IP_WHITELIST | JSON | No | Admin API IP whitelist; when configured, only listed IPs may access /admin/* | []; no IP restriction | ["203.0.113.10"] |
DISABLE_ADMIN_PASSWORD_CHECK | Text/JSON | No | Warning: skip Admin console password or user checks | false | true |
When ADMIN_API_IP_WHITELIST is unset or empty, source IPs are not restricted. Once configured, it applies to both admin-password and Admin user-token access, trusts only Cloudflare's CF-Connecting-IP header, and denies requests without that header.
Email Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
PREFIX | Text | No | Default prefix for new email address names | Empty; no prefix | tmp |
MIN_ADDRESS_LEN | Number | No | Minimum length of email address name | 1 | 1 |
MAX_ADDRESS_LEN | Number | No | Maximum length of email address name | 30 | 30 |
DISABLE_CUSTOM_ADDRESS_NAME | Text/JSON | No | Disable custom email address names; when enabled, users cannot enter custom names and they are generated automatically | false | true |
DISABLE_ADDRESS_UPDATED_AT | Text/JSON | No | Stop individual and user-wide address activity keep-alive updates and disable built-in manual and scheduled inactive-address cleanup. Initial address timestamps, password operations, and other cleanup rules remain unchanged | false | true |
ADDRESS_CHECK_REGEX | Text | No | Regular expression for email address name, used for validation only | Empty; no check | ^(?!.*admin).* |
ADDRESS_REGEX | Text | No | Regular expression used to replace illegal symbols in email address names. Use with caution because some symbols may prevent mail reception | [^a-z0-9] | [^a-z0-9] |
DEFAULT_DOMAINS | JSON | No | Default domains available to users (not logged in or users without assigned roles) | Falls back to DOMAINS | ["awsl.uk", "dreamhunter2333.xyz"] |
CREATE_ADDRESS_DEFAULT_DOMAIN_FIRST | Text/JSON | No | Prioritize the first default domain when creating an address without an explicit domain, mainly for Telegram Bot scenarios | false | true |
ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH | Text/JSON | No | Allow create-address APIs to use base-domain suffix matching. When enabled, if example.com is allowed, /api/new_address and /admin/new_address can also accept foo.example.com or a.b.example.com | false when no Admin override exists | true |
RANDOM_SUBDOMAIN_DOMAINS | JSON | No | Base domains that allow random or manual subdomains; random mode can turn [email protected] into name@<random>.abc.com | []; disabled | ["abc.com"] |
RANDOM_SUBDOMAIN_LENGTH | Number | No | Random subdomain length, valid range 1-63 | 8 | 8 |
DOMAIN_LABELS | JSON | No | For Chinese domains, use DOMAIN_LABELS to display localized names | []; original names | ["中文.awsl.uk", "dreamhunter2333.xyz"] |
ENABLE_AUTO_REPLY | Text/JSON | No | Allow automatic email replies. Sender filter (source_prefix) supports three modes: empty to match all senders, prefix for startsWith matching, or /regex/ syntax for regex matching (e.g. /@example\.com$/) | false | true |
DEFAULT_SEND_BALANCE | Number/Text | No | Default email sending balance. When greater than 0, it is auto-initialized when users open the settings page or send mail for the first time | 0 | 1 |
ENABLE_ADDRESS_PASSWORD | Text/JSON | No | Enable address password support; passwords are generated for new addresses and can be used for login and modification | false | true |
ADDRESS_PASSWORD_LOGIN_ONLY | Text/JSON | No | Effective only with ENABLE_ADDRESS_PASSWORD=true. Shows only password login and issues renewable 30-day mailbox JWTs at creation, login, and authorized access. Legacy credentials, links, and API access remain compatible. See mailbox sessions | false | true |
ENABLE_AGENT_EMAIL_INFO | Text/JSON | No | Show AI Agent access info in the frontend "Address Credentials & Connection Methods" dialog (Address JWT, parsed-mail APIs, skill link) | false | true |
SMTP_IMAP_PROXY_CONFIG | JSON | No | Show SMTP/IMAP proxy connection info in the frontend "Address Credentials & Connection Methods" dialog; display-only, does not start the proxy service, which must be deployed separately | Empty; hidden | See example below |
SEND_MAIL_DOMAINS | JSON | No | Restrict which sender domains can use the SEND_MAIL binding | []; all domains allowed | ["example.com", "mail.example.com"] |
NOTE
When DEFAULT_DOMAINS is unset or configured as an empty array, it falls back to DOMAINS.
RANDOM_SUBDOMAIN_DOMAINS defines the base-domain scope shared by the frontend random and manual subdomain modes. It does not create Cloudflare-side subdomain routing for you.
To actually receive mail on addresses like name@<random>.abc.com, you must add a wildcard * MX record under the base domain in DNS by copying the apex's existing MX records to host * (preserving each record's priority and target). Cloudflare Email Routing does not inherit the apex configuration onto subdomains — see the Cloudflare Email Routing — Subdomains docs, #1035 and Configure Subdomain Email.
Subdomain addresses are usually best used for receiving only; for sending, prefer the main domain.
ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH is independent from those frontend modes. It lets API callers directly specify subdomains such as foo.example.com under other allowed base domains.
ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH precedence: if the env is explicitly set to false, the feature is globally forced off; otherwise the persisted admin setting takes precedence, and the env value is only used as a fallback when no admin setting has been saved.
The admin panel exposes three explicit states: Follow Environment Variable, Force Enable, and Force Disable. Saving Follow Environment Variable clears the admin override and returns the feature to the "unset" fallback behavior.
SEND_MAIL_DOMAINS only affects the SEND_MAIL binding fallback path and /admin/send_mail_by_binding. It does not affect Resend, SMTP, or verifiedAddressList.
SMTP_IMAP_PROXY_CONFIG example:
{
"smtp": { "host": "smtp.example.com", "port": 8025, "starttls": true },
"imap": { "host": "imap.example.com", "port": 11143, "starttls": true }
}SMTP and IMAP can use different hostnames, which is useful for reverse proxies or separate port mappings.
Email Reception Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
BLACK_LIST | Text | No | Comma-separated sender blacklist; case-sensitive substring matching against the SMTP envelope sender and every email address parsed from From, independently of body parsing. Any match rejects the mail. The admin sender blacklist follows the same rule; display names are not matched. | Empty; no blocking | gov.cn,edu.cn |
ENABLE_CHECK_JUNK_MAIL | Text/JSON | No | Whether to enable junk mail checking, used with the following two lists | false | true |
JUNK_MAIL_CHECK_LIST | JSON | No | Existence check; registered failure/error results are junk, while none and SPF/DKIM neutral are treated as absent | [] | ["spf", "dkim", "dmarc"] |
JUNK_MAIL_FORCE_PASS_LIST | JSON | No | Strict pass check; every item must explicitly return pass, otherwise it is treated as junk | [] | ["spf", "dkim", "dmarc"] |
FORWARD_ADDRESS_LIST | JSON | No | Global external-only forwarding via Cloudflare; does not use internal mailbox delivery | []; disabled | ["[email protected]"] |
REMOVE_EXCEED_SIZE_ATTACHMENT | Text/JSON | No | If attachment exceeds 2MB, remove it; email may lose some information due to parsing | false | true |
REMOVE_ALL_ATTACHMENT | Text/JSON | No | Remove all attachments; email may lose some information due to parsing | false | true |
ENABLE_MAIL_GZIP | Text/JSON | No | When enabled, new emails are gzip-compressed and stored in raw_blob column to save D1 database space. Existing plaintext raw data is automatically compatible for reading. Run database migration first (Admin -> Quick Setup -> Database -> Migrate Database or POST /admin/db_migration) to ensure the raw_blob column exists before enabling. This feature adds compression/decompression CPU overhead, so enabling it on a paid Cloudflare Worker plan is recommended. | false | true |
CLEANUP_BATCH_SIZE | Number | No | Per-run limit for built-in mail, sent-mail, and address cleanup tasks, valid range 1-5000. Smaller values reduce per-run D1 pressure; larger values clear backlogs faster | 3000 | 3000 |
NOTE
Authentication results follow their standards: SPF none means no usable domain or SPF record was found, and SPF neutral must be treated like none; DKIM none means the message was unsigned, and DKIM neutral is also treated as unsigned; DMARC none means no applicable DMARC policy was found. Unregistered results and unsupported method versions are ignored. JUNK_MAIL_CHECK_LIST treats these results as absent, while JUNK_MAIL_FORCE_PASS_LIST still requires an explicit supported pass
ENABLE_MAIL_GZIP adds CPU cost for gzip compression on write and decompression on read. Free-tier Workers are more likely to hit CPU limits, so a paid plan is recommended before enabling it
Junk mail checking and attachment removal require email parsing, free tier CPU is limited, may cause large email parsing timeout
If you want stronger email parsing capabilities
Webhook Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
ENABLE_WEBHOOK | Text/JSON | No | Whether to enable webhook | false | true |
FRONTEND_URL | Text | No | Frontend URL, used for sending webhook email URLs | Empty | https://xxxx.xxx |
BACKEND_URL | Text | No | Public backend base URL for signed attachment links | Empty; attachment URLs omitted | https://temp-email-api.example.com |
NOTE
Webhook functionality requires email parsing, free tier CPU is limited, may cause large email parsing timeout
If you want stronger email parsing capabilities
User Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
USER_DEFAULT_ROLE | Text | No | Default role for new users, only effective when email verification is enabled | Empty; no role assigned | vip |
ADMIN_USER_ROLE | Text | No | Users whose role equals ADMIN_USER_ROLE can access the Admin Console | Empty; no role grants Admin access | admin |
USER_ROLES | JSON | No | Custom user-role list; role is a custom name, while vip and admin are examples only | [] | See below |
DISABLE_ANONYMOUS_USER_CREATE_EMAIL | Text/JSON | No | Disable anonymous user mailbox creation; when enabled, users can create addresses only after login | false | true |
NO_LIMIT_SEND_ROLE | Text | No | Roles that can send unlimited emails, multiple roles separated by commas | Empty; all roles use balance checks | vip,admin |
USER_ROLES User Role Configuration
- Role names are defined by the deployer;
vipandadminin the examples are not built-in roles.USER_DEFAULT_ROLE,ADMIN_USER_ROLE, andNO_LIMIT_SEND_ROLErefer to these configurations by the same role name - If
domainsis empty,DEFAULT_DOMAINSwill be used; ifDEFAULT_DOMAINSis also empty, it falls back toDOMAINS - If prefix is null, the default prefix will be used, if prefix is an empty string, no prefix will be used
When deploying through UI, configure USER_ROLES in this format: [{"domains":["awsl.uk","dreamhunter2333.xyz"],"role":"vip","prefix":"vip"},{"domains":["awsl.uk","dreamhunter2333.xyz"],"role":"admin","prefix":""}]
When deploying via CLI, refer to worker/wrangler.toml.template and configure USER_ROLES in this format: [{ domains = ["awsl.uk", "dreamhunter2333.xyz"], role = "vip", prefix = "vip" }, { domains = ["awsl.uk", "dreamhunter2333.xyz"], role = "admin", prefix = "" }]
Web Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
DEFAULT_LANG | Text | No | Worker error message default language, supports zh/en | General APIs fall back to en; Telegram falls back to zh | zh |
TITLE | Text | No | Custom frontend page website title, supports HTML | Built-in localized title | Custom Title |
ANNOUNCEMENT | Text | No | Custom frontend page announcement, supports HTML | Empty; hidden | Custom Announcement |
ALWAYS_SHOW_ANNOUNCEMENT | Text/JSON | No | Whether to always show an announcement even when unchanged | false | true |
COPYRIGHT | Text | No | Custom frontend footer text, supports HTML | Dream Hunter | Custom Copyright |
ADMIN_CONTACT | Text | No | Admin contact information, can be any string | Empty; hidden | [email protected] |
DISABLE_SHOW_GITHUB | Text/JSON | No | Globally hide the GitHub link | false; visible | true |
DISABLE_SHOW_GITHUB_FOR_USER | Text/JSON | No | Hide the GitHub link for normal users while keeping it visible to Admin users | false; visible | true |
STATUS_URL | Text | No | Status monitoring page URL, shows Status menu button when configured | Empty; hidden | https://status.example.com |
CF_TURNSTILE_SITE_KEY | Text/Secret | No | Turnstile CAPTCHA configuration (for new address creation, registration code, etc.) | Empty; related checks disabled | xxx |
CF_TURNSTILE_SECRET_KEY | Text/Secret | No | Turnstile CAPTCHA configuration (for new address creation, registration code, etc.) | Empty; related checks disabled | xxx |
ENABLE_GLOBAL_TURNSTILE_CHECK | Text/JSON | No | Enable global Turnstile CAPTCHA for all login forms (Admin login, user login, address password login), requires Turnstile keys above | false | true |
Telegram Bot Related Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
TG_MAX_ADDRESS | Number | No | Maximum number of mailboxes that can be bound to the Telegram Bot | 5 | 5 |
TG_BOT_INFO | Text | No | Predefined Bot info can reduce webhook latency | Empty; queried at runtime | {} |
TG_ALLOW_USER_LANG | Text/JSON | No | Allow users to switch language via /lang command | false | true |
ENABLE_TG_PUSH_ATTACHMENT | Text/JSON | No | Enable sending email attachments via Telegram push, 50MB per file limit | false | true |
NOTE
Telegram functionality requires email parsing, free tier CPU is limited, may cause large email parsing timeout
If you want stronger email parsing capabilities
Email Forwarding Related Variables
Admin or SUBDOMAIN_FORWARD_ADDRESS_LIST rules targeting addresses under domains listed in DOMAINS reuse receive processing for storage, extraction and notifications, but do not forward or auto-reply again. Unknown addresses follow the existing recipient-rejection setting. Originals are kept by default; enable “Delete original after forwarding” in a rule to delete the current original at the end of mail processing after successful delivery. FORWARD_ADDRESS_LIST only forwards to external addresses through Cloudflare and does not use internal mailbox delivery. No database migration is required.
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
SUBDOMAIN_FORWARD_ADDRESS_LIST | JSON | No | Subdomain/rule forwarding configuration, supports filtering by domain and source regex | []; disabled | See below |
SUBDOMAIN_FORWARD_ADDRESS_LIST Configuration
v1.2.0 added sourcePatterns and sourceMatchMode fields for filtering by sender address regex:
domains: Target domain list, matches all domains if emptyforward: Forward destination addressdeleteOriginal: Delete the original at the end of mail processing after this rule succeeds (optional, defaultfalse; self-forwards and failures do not delete it; original mail and attachment links stop working after deletion)sourcePatterns: Source address regex list (optional)sourceMatchMode: Match mode,any(match any, default) orall(match all)recipientPatterns,recipientMatchMode: Optional recipient regex list andany(default) /allmatching mode, using the same behavior as sender filters
Domain, sender and recipient filters must all match; empty filters are ignored. Regex matching is case-insensitive against the full envelope address, not MIME headers. For example, {"domains":["example.com"],"forward":"[email protected]","recipientPatterns":["^[^@]*admin[^@]*@"]} routes recipients containing admin to the internal admin mailbox. Disable “Block receive unknown address email” if the original recipient is not a registered mailbox. Existing rejection, forwarding and deletion behavior is unchanged; no database migration is required.
Regex pattern max length is 200 characters to prevent ReDoS attacks
SUBDOMAIN_FORWARD_ADDRESS_LIST = """
[
{"domains":[""],"forward":"[email protected]"},
{"domains":["subdomain-1.domain.com","subdomain-2.domain.com"],"forward":"[email protected]"},
{"domains":["example.com"],"forward":"[email protected]","sourcePatterns":[".*@github.com",".*@gitlab.com"],"sourceMatchMode":"any"}
]
"""Other Variables
| Variable Name | Type | Required | Description | Default / When unset | Example |
|---|---|---|---|---|---|
ENABLE_ANOTHER_WORKER | Text/JSON | No | Whether to enable other Workers to process emails | false | true |
ANOTHER_WORKER_LIST | JSON | No | - Configuration for other Workers to process emails; multiple Workers can be configured - Filter by keywords and call the bound Worker's method (default method name is rpcEmail)- keywords is required; otherwise the Worker is not triggered | [] | See below |
NOTE
ANOTHER_WORKER_LIST configuration example
#ANOTHER_WORKER_LIST ="""
#[
# {
# "binding":"AUTH_INBOX",
# "method":"rpcEmail",
# "keywords":[
# "验证码","激活码","激活链接","确认链接","验证邮箱","确认邮件","账号激活","邮件验证","账户确认","安全码","认证码","安全验证","登陆码","确认码","启用账户","激活账户","账号验证","注册确认",
# "account","activation","verify","verification","activate","confirmation","email","code","validate","registration","login","code","expire","confirm"
# ]
# }
#]
#