Skip to content

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 NameTypeRequiredDescriptionDefault / When unsetExample
DOMAINSJSONYesAll domains for temporary email, supports multiple domainsNone["awsl.uk", "dreamhunter2333.xyz"]
JWT_SECRETText/SecretYesSecret key for signing JWTs used in login and authentication. Use a random string, e.g. generated via openssl rand -hex 32Nonea1b2c3d4...
ADMIN_PASSWORDSJSONNoAdmin console passwords; admin password login is disabled when unset[]["123", "456"]
DISABLE_USER_SYSTEMText/JSONNoBlock user system APIs and hide user interfacesfalsetrue
ENABLE_USER_CREATE_EMAILText/JSONNoWhether to allow users to create mailboxesfalsetrue
ENABLE_USER_DELETE_EMAILText/JSONNoWhether to allow users to delete emailsfalsetrue
ENABLE_MAIL_READ_STATUSText/JSONNoEnables read/unread mail state. Upgrade the database schema before enablingfalsetrue
ENABLE_REDEEM_CODEText/JSONNoEnables the redemption page, public redemption APIs, and Admin redemption managementfalsetrue
REDEEM_CODE_URLTextNoExternal URL for obtaining redemption codesEmpty; link hiddenhttps://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.

Variable NameTypeRequiredDescriptionDefault / When unsetExample
PASSWORDSJSONNoWebsite private passwords, required after configuration[]; public access["123", "456"]
ADMIN_API_IP_WHITELISTJSONNoAdmin API IP whitelist; when configured, only listed IPs may access /admin/*[]; no IP restriction["203.0.113.10"]
DISABLE_ADMIN_PASSWORD_CHECKText/JSONNoWarning: skip Admin console password or user checksfalsetrue

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.

Variable NameTypeRequiredDescriptionDefault / When unsetExample
PREFIXTextNoDefault prefix for new email address namesEmpty; no prefixtmp
MIN_ADDRESS_LENNumberNoMinimum length of email address name11
MAX_ADDRESS_LENNumberNoMaximum length of email address name3030
DISABLE_CUSTOM_ADDRESS_NAMEText/JSONNoDisable custom email address names; when enabled, users cannot enter custom names and they are generated automaticallyfalsetrue
DISABLE_ADDRESS_UPDATED_ATText/JSONNoStop 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 unchangedfalsetrue
ADDRESS_CHECK_REGEXTextNoRegular expression for email address name, used for validation onlyEmpty; no check^(?!.*admin).*
ADDRESS_REGEXTextNoRegular 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_DOMAINSJSONNoDefault domains available to users (not logged in or users without assigned roles)Falls back to DOMAINS["awsl.uk", "dreamhunter2333.xyz"]
CREATE_ADDRESS_DEFAULT_DOMAIN_FIRSTText/JSONNoPrioritize the first default domain when creating an address without an explicit domain, mainly for Telegram Bot scenariosfalsetrue
ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCHText/JSONNoAllow 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.comfalse when no Admin override existstrue
RANDOM_SUBDOMAIN_DOMAINSJSONNoBase domains that allow random or manual subdomains; random mode can turn [email protected] into name@<random>.abc.com[]; disabled["abc.com"]
RANDOM_SUBDOMAIN_LENGTHNumberNoRandom subdomain length, valid range 1-6388
DOMAIN_LABELSJSONNoFor Chinese domains, use DOMAIN_LABELS to display localized names[]; original names["中文.awsl.uk", "dreamhunter2333.xyz"]
ENABLE_AUTO_REPLYText/JSONNoAllow 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$/)falsetrue
DEFAULT_SEND_BALANCENumber/TextNoDefault email sending balance. When greater than 0, it is auto-initialized when users open the settings page or send mail for the first time01
ENABLE_ADDRESS_PASSWORDText/JSONNoEnable address password support; passwords are generated for new addresses and can be used for login and modificationfalsetrue
ADDRESS_PASSWORD_LOGIN_ONLYText/JSONNoEffective 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 sessionsfalsetrue
ENABLE_AGENT_EMAIL_INFOText/JSONNoShow AI Agent access info in the frontend "Address Credentials & Connection Methods" dialog (Address JWT, parsed-mail APIs, skill link)falsetrue
SMTP_IMAP_PROXY_CONFIGJSONNoShow 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 separatelyEmpty; hiddenSee example below
SEND_MAIL_DOMAINSJSONNoRestrict 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:

json
{
  "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.

Variable NameTypeRequiredDescriptionDefault / When unsetExample
BLACK_LISTTextNoComma-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 blockinggov.cn,edu.cn
ENABLE_CHECK_JUNK_MAILText/JSONNoWhether to enable junk mail checking, used with the following two listsfalsetrue
JUNK_MAIL_CHECK_LISTJSONNoExistence check; registered failure/error results are junk, while none and SPF/DKIM neutral are treated as absent[]["spf", "dkim", "dmarc"]
JUNK_MAIL_FORCE_PASS_LISTJSONNoStrict pass check; every item must explicitly return pass, otherwise it is treated as junk[]["spf", "dkim", "dmarc"]
FORWARD_ADDRESS_LISTJSONNoGlobal external-only forwarding via Cloudflare; does not use internal mailbox delivery[]; disabled["[email protected]"]
REMOVE_EXCEED_SIZE_ATTACHMENTText/JSONNoIf attachment exceeds 2MB, remove it; email may lose some information due to parsingfalsetrue
REMOVE_ALL_ATTACHMENTText/JSONNoRemove all attachments; email may lose some information due to parsingfalsetrue
ENABLE_MAIL_GZIPText/JSONNoWhen 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.falsetrue
CLEANUP_BATCH_SIZENumberNoPer-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 faster30003000

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

Refer to Configure worker to use wasm for email parsing

Variable NameTypeRequiredDescriptionDefault / When unsetExample
ENABLE_WEBHOOKText/JSONNoWhether to enable webhookfalsetrue
FRONTEND_URLTextNoFrontend URL, used for sending webhook email URLsEmptyhttps://xxxx.xxx
BACKEND_URLTextNoPublic backend base URL for signed attachment linksEmpty; attachment URLs omittedhttps://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

Refer to Configure worker to use wasm for email parsing

Variable NameTypeRequiredDescriptionDefault / When unsetExample
USER_DEFAULT_ROLETextNoDefault role for new users, only effective when email verification is enabledEmpty; no role assignedvip
ADMIN_USER_ROLETextNoUsers whose role equals ADMIN_USER_ROLE can access the Admin ConsoleEmpty; no role grants Admin accessadmin
USER_ROLESJSONNoCustom user-role list; role is a custom name, while vip and admin are examples only[]See below
DISABLE_ANONYMOUS_USER_CREATE_EMAILText/JSONNoDisable anonymous user mailbox creation; when enabled, users can create addresses only after loginfalsetrue
NO_LIMIT_SEND_ROLETextNoRoles that can send unlimited emails, multiple roles separated by commasEmpty; all roles use balance checksvip,admin

USER_ROLES User Role Configuration

  • Role names are defined by the deployer; vip and admin in the examples are not built-in roles. USER_DEFAULT_ROLE, ADMIN_USER_ROLE, and NO_LIMIT_SEND_ROLE refer to these configurations by the same role name
  • If domains is empty, DEFAULT_DOMAINS will be used; if DEFAULT_DOMAINS is also empty, it falls back to DOMAINS
  • 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 = "" }]

Variable NameTypeRequiredDescriptionDefault / When unsetExample
DEFAULT_LANGTextNoWorker error message default language, supports zh/enGeneral APIs fall back to en; Telegram falls back to zhzh
TITLETextNoCustom frontend page website title, supports HTMLBuilt-in localized titleCustom Title
ANNOUNCEMENTTextNoCustom frontend page announcement, supports HTMLEmpty; hiddenCustom Announcement
ALWAYS_SHOW_ANNOUNCEMENTText/JSONNoWhether to always show an announcement even when unchangedfalsetrue
COPYRIGHTTextNoCustom frontend footer text, supports HTMLDream HunterCustom Copyright
ADMIN_CONTACTTextNoAdmin contact information, can be any stringEmpty; hidden[email protected]
DISABLE_SHOW_GITHUBText/JSONNoGlobally hide the GitHub linkfalse; visibletrue
DISABLE_SHOW_GITHUB_FOR_USERText/JSONNoHide the GitHub link for normal users while keeping it visible to Admin usersfalse; visibletrue
STATUS_URLTextNoStatus monitoring page URL, shows Status menu button when configuredEmpty; hiddenhttps://status.example.com
CF_TURNSTILE_SITE_KEYText/SecretNoTurnstile CAPTCHA configuration (for new address creation, registration code, etc.)Empty; related checks disabledxxx
CF_TURNSTILE_SECRET_KEYText/SecretNoTurnstile CAPTCHA configuration (for new address creation, registration code, etc.)Empty; related checks disabledxxx
ENABLE_GLOBAL_TURNSTILE_CHECKText/JSONNoEnable global Turnstile CAPTCHA for all login forms (Admin login, user login, address password login), requires Turnstile keys abovefalsetrue
Variable NameTypeRequiredDescriptionDefault / When unsetExample
TG_MAX_ADDRESSNumberNoMaximum number of mailboxes that can be bound to the Telegram Bot55
TG_BOT_INFOTextNoPredefined Bot info can reduce webhook latencyEmpty; queried at runtime{}
TG_ALLOW_USER_LANGText/JSONNoAllow users to switch language via /lang commandfalsetrue
ENABLE_TG_PUSH_ATTACHMENTText/JSONNoEnable sending email attachments via Telegram push, 50MB per file limitfalsetrue

NOTE

Telegram functionality requires email parsing, free tier CPU is limited, may cause large email parsing timeout

If you want stronger email parsing capabilities

Refer to Configure worker to use wasm for email parsing

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 NameTypeRequiredDescriptionDefault / When unsetExample
SUBDOMAIN_FORWARD_ADDRESS_LISTJSONNoSubdomain/rule forwarding configuration, supports filtering by domain and source regex[]; disabledSee 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 empty
  • forward: Forward destination address
  • deleteOriginal: Delete the original at the end of mail processing after this rule succeeds (optional, default false; 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) or all (match all)
  • recipientPatterns, recipientMatchMode: Optional recipient regex list and any (default) / all matching 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

toml
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 NameTypeRequiredDescriptionDefault / When unsetExample
ENABLE_ANOTHER_WORKERText/JSONNoWhether to enable other Workers to process emailsfalsetrue
ANOTHER_WORKER_LISTJSONNo- 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

toml
#ANOTHER_WORKER_LIST ="""
#[
#    {
#        "binding":"AUTH_INBOX",
#        "method":"rpcEmail",
#        "keywords":[
#            "验证码","激活码","激活链接","确认链接","验证邮箱","确认邮件","账号激活","邮件验证","账户确认","安全码","认证码","安全验证","登陆码","确认码","启用账户","激活账户","账号验证","注册确认",
#            "account","activation","verify","verification","activate","confirmation","email","code","validate","registration","login","code","expire","confirm"
#        ]
#    }
#]
#

Docs adapted from the MIT-licensed cloudflare_temp_email project — License & attribution