Cloudflare Temp Email 新建邮箱地址 API 实战指南admin/new_address 与子域名匹配机制详解【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email本文聚焦 cloudflare_temp_email 项目的新建邮箱地址 API系统讲解/admin/new_address与/api/new_address两个端点的请求参数、认证方式地址 JWT vs 用户 JWT、子域名匹配与随机子域名生成机制并通过批量创建随机邮箱的完整 Python 示例帮助你快速掌握以编程方式批量获取临时邮箱的能力。一、两种 JWT地址 JWT 与用户 JWT切勿混淆本项目的 API 体系中存在两套完全独立的 JWT 认证方式使用场景与携带位置均不相同对比项地址 JWT用户 JWT获取方式通过/api/new_address或/admin/new_address创建邮箱时返回通过/user_api/login或/user_api/register获得携带位置Authorization: Bearer jwtheaderx-user-token: jwtheader访问范围/api/*接口查看邮件、删除邮件等/user_api/*接口用户账户管理地址 JWT 由创建接口在返回体中直接给出{jwt: Jwt, ...}其内容在 common.ts 中通过Jwt.sign({ address, address_id }, JWT_SECRET, HS256)生成本质上是「地址身份凭证」——拿到它即可代表该地址访问邮件 CRUD 接口。从源码结构看地址 JWT 的载荷只包含address与address_id两个字段与用户账户体系完全解耦。注意地址 JWT 无法访问/user_api/*接口用户 JWT 也不能直接访问/api/*的邮件接口两者必须按文档约定分别使用。二、通过 admin API 新建邮箱地址/admin/new_address由 address_api.ts 中的createNewAddress处理属于管理后台端点使用管理员认证x-admin-authheader。以下是最基本的 Python 调用示例使用requests库import requests res requests.post( # 替换 xxxx.xxxx 为你的 worker 域名 https://xxxx.xxxx/admin/new_address, json{ # 是否启用前缀 (True/False) enablePrefix: True, name: 邮箱名称, domain: 邮箱域名, }, headers{ x-admin-auth: 你的网站admin密码, # x-custom-auth: 你的网站密码, # 如果启用了私有站点密码 Content-Type: application/json } ) # 返回值 {jwt: Jwt, address: 邮箱地址, address_id: 123} print(res.json())2.1 请求参数说明enablePrefix布尔是否启用前缀。为true时会在邮箱名前拼上前缀由环境变量PREFIX或用户角色的prefix配置决定。参考 common.ts 中的前缀拼接逻辑若传入addressPrefix字符串则优先使用否则在enablePrefix为真时使用c.env.PREFIX。name字符串邮箱名称即前的本地部分。若不传 nameadmin 接口会直接返回400 RequiredFieldMsg见 address_api.ts而匿名接口/api/new_address在不传 name 时则会自动生成随机名称见 new_address.ts。domain字符串邮箱域名。若不传系统会根据CREATE_ADDRESS_DEFAULT_DOMAIN_FIRST环境变量决定为true时取allowDomains[0]否则从允许域名列表中随机选取见 common.ts。x-admin-auth管理后台密码对应ADMIN_PASSWORDS环境变量。x-custom-auth可选。当站点配置了私有站点密码PASSWORDS环境变量时需要携带。返回体结构为{jwt: Jwt, address: 邮箱地址, address_id: 123}若配置了地址密码功能ENABLE_ADDRESS_PASSWORD返回体中还会包含password字段见 common.ts。2.2 与匿名创建接口的差异管理员端点/admin/new_address与匿名端点/api/new_address在参数校验上存在明显差异对比 address_api.ts 与 new_address.tsname 校验admin 接口要求 name 必填匿名接口允许空 name自动随机生成但受DISABLE_CUSTOM_ADDRESS_NAME控制。长度限制admin 接口checkLengthByConfig: false仅受硬编码的最小 1 / 最大 30 限制匿名接口checkLengthByConfig: true遵循MIN_ADDRESS_LEN/MAX_ADDRESS_LEN环境变量。域名校验admin 接口checkAllowDomains: false只要域名在全局DOMAINS列表内即可匿名接口会校验用户角色允许的域名。正则校验admin 接口enableCheckNameRegex: false匿名接口默认开启ADDRESS_CHECK_REGEX校验。sourceMetaadmin 接口标记为admin匿名接口会从CF-Connecting-IP、X-Forwarded-For等请求头提取来源信息用于地址溯源。频控匿名接口在禁用匿名创建时还会检查地址数量上限isAddressCountLimitReached。三、创建子域名邮箱地址子域名匹配机制如果你已经将基础域名配置进DOMAINS/DEFAULT_DOMAINS/USER_ROLES并开启ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH管理后台也可单独开关那么创建地址 API 可以直接接收子域名import requests res requests.post( https://xxxx.xxxx/admin/new_address, json{ enablePrefix: True, name: project001, domain: team.example.com, }, headers{ x-admin-auth: 你的网站admin密码, Content-Type: application/json } )3.1 匹配规则以DOMAINS中包含example.com为例若允许域名里有example.com则team.example.com、dev.team.example.com都可以匹配成功badexample.com这种不是点分后缀的域名不会被误判为example.com——匹配要求子域名与基础域名之间以.分隔成独立标签且标签需通过areValidDomainLabels校验见 common.ts 的findMatchedAllowedDomain实现domainLabels比allowDomainLabels长、且尾部标签与基础域名完全一致才算命中这与RANDOM_SUBDOMAIN_DOMAINS不同这里是由调用方显式指定子域名不是系统自动生成随机子域名。3.2 开关优先级环境变量 vs 管理后台getAddressCreationSubdomainMatchStatuscommon.ts实现了三层优先级逻辑环境变量ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH为false时作为全局 kill switch后台开关无法强行打开后台存储的开关值AddressCreationSettings.enableSubdomainMatch优先于环境变量生效两者都未配置时回退到环境变量值。管理后台可以把该能力设置为「跟随环境变量 / 强制开启 / 强制关闭」其中「跟随环境变量」会清空后台覆盖值恢复到未设置后台覆盖后按环境变量回退。对应配置参考 wrangler.toml.template# Allow /api/new_address and /admin/new_address to accept subdomains that end with an allowed base domain # e.g. if DOMAINS contains abc.com, API can accept team.abc.com and dev.team.abc.com # ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH true四、随机子域名生成RANDOM_SUBDOMAIN_DOMAINS与「显式指定子域名」不同RANDOM_SUBDOMAIN_DOMAINS是自动生成随机子域名。当请求体携带enableRandomSubdomain: true且目标域名命中RANDOM_SUBDOMAIN_DOMAINS列表时系统会按RANDOM_SUBDOMAIN_LENGTH默认 8 位生成[a-z0-9]字符集的随机子域名最终地址形如namer4nd0m.abc.com见 common.ts 的generateRandomSubdomain与 wrangler.toml.template 的注释示例。实现细节common.ts若enableRandomSubdomain为真但域名不在RANDOM_SUBDOMAIN_DOMAINS中返回RandomSubdomainNotAllowedMsg错误生成地址后写入 D1若遇UNIQUE冲突会重试最大尝试次数由MAX_RANDOM_SUBDOMAIN_ATTEMPTS控制随机子域名的长度被钳制在 163DNS 标签上限之间。# Allow optional random subdomain generation for the listed base domains # e.g. nameabc.com namer4nd0m.abc.com # RANDOM_SUBDOMAIN_DOMAINS [abc.com] # RANDOM_SUBDOMAIN_LENGTH 8五、批量创建随机用户名邮箱地址完整 Python 示例实际生产场景中往往需要一次性批量创建多个临时邮箱。以下示例使用requestsconcurrent.futures并发创建随机邮箱并把结果邮箱地址 地址 JWT追加写入本地文件import requests import random import string from concurrent.futures import ThreadPoolExecutor, as_completed def generate_random_name(): # 生成5位英文字符 letters1 .join(random.choices(string.ascii_lowercase, k5)) # 生成1-3个数字 numbers .join(random.choices(string.digits, krandom.randint(1, 3))) # 生成1-3个英文字符 letters2 .join(random.choices(string.ascii_lowercase, krandom.randint(1, 3))) # 组合成最终名称 return letters1 numbers letters2 def fetch_email_data(name): try: res requests.post( https://worker 域名/admin/new_address, json{ enablePrefix: True, name: name, domain: 邮箱域名, }, headers{ x-admin-auth: 你的网站admin密码, # x-custom-auth: 你的网站密码, # 如果启用了私有站点密码 Content-Type: application/json } ) if res.status_code 200: response_data res.json() email response_data.get(address, 无地址) jwt response_data.get(jwt, 无jwt) return f{email}----{jwt}\n else: print(f请求失败状态码: {res.status_code}) return None except requests.RequestException as e: print(f请求出现错误: {e}) return None def generate_and_save_emails(num_emails): with ThreadPoolExecutor(max_workers30) as executor, open(email.txt, a) as file: futures [executor.submit(fetch_email_data, generate_random_name()) for _ in range(num_emails)] for future in as_completed(futures): result future.result() if result: file.write(result) # 生成10个邮箱并追加到现有文件 generate_and_save_emails(10)5.1 脚本要点拆解随机名称生成generate_random_name组合 5 位小写字母、13 位数字、13 位小写字母得到的名称符合ADDRESS_REGEX的默认字符集要求仅小写字母与数字。并发控制ThreadPoolExecutor(max_workers30)控制并发度避免瞬时请求过猛触发 Worker 限流实际部署时应根据自身 Worker 配额如免费版 100k requests/day调整并发数与批量大小。结果落盘以邮箱----JWT格式追加写入email.txt每条记录同时保存地址与地址 JWT方便后续直接用该 JWT 调用/api/*接口查收邮件。错误处理非 200 响应与网络异常均被捕获并打印不会中断整个批处理流程。5.2 批量场景下的关键限制若启用DISABLE_ANONYMOUS_USER_CREATE_EMAIL且以登录用户身份调用/api/new_address会受isAddressCountLimitReached的地址数量上限约束见 new_address.ts批量创建时需注意配额名称命中ADDRESS_BLOCK_LIST_KEY黑名单如管理后台配置的屏蔽词时会返回Name[...]is blocked错误见 new_address.ts地址写入 D1 采用事务保证唯一性重复创建相同地址会返回AddressAlreadyExistsMsg见 common.ts。六、相关环境变量速查环境变量作用默认值ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH允许 API 接收基础域名的任意子域名未设置后台可覆盖RANDOM_SUBDOMAIN_DOMAINS允许自动生成随机子域名的基础域名列表空RANDOM_SUBDOMAIN_LENGTH随机子域名长度8MIN_ADDRESS_LEN/MAX_ADDRESS_LEN邮箱名称最小/最大长度匿名接口生效1 / 30DISABLE_CUSTOM_ADDRESS_NAME禁止自定义名称强制随机生成falseADDRESS_CHECK_REGEX名称必须匹配的正则匿名接口生效无CREATE_ADDRESS_DEFAULT_DOMAIN_FIRST未指定域名时是否使用默认域名列表的第一个falsePREFIX启用enablePrefix时的默认前缀无ENABLE_ADDRESS_PASSWORD创建地址时自动生成地址密码falseDISABLE_ANONYMOUS_USER_CREATE_EMAIL禁止匿名创建地址要求登录false以上环境变量的完整注释可参考 wrangler.toml.template类型声明见 types.d.ts。七、接口路由与源码索引匿名创建POST /api/new_address→ new_address.ts路由注册于 mails_api/index.ts管理端创建POST /admin/new_address→ address_api.ts路由注册于 admin_api/index.ts核心创建逻辑newAddress含前缀拼接、域名校验、随机子域名、JWT 签发→ common.ts随机名称生成generateRandomName→ common.ts域名匹配与开关优先级findMatchedAllowedDomain/getAddressCreationSubdomainMatchStatus→ common.ts。通过上述接口与机制你可以将临时邮箱的创建能力无缝集成到自动化测试、账号批量注册、数据采集等场景中——创建时保存好返回的地址 JWT后续即可用它直接拉取该地址收到的邮件。【免费下载链接】cloudflare_temp_emailCloudFlare free temp domain email 免费收发 临时域名邮箱 支持附件 IMAP SMTP TelegramBot项目地址: https://gitcode.com/GitHub_Trending/cl/cloudflare_temp_email创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考