feat: 支持创建邮箱 API 的子域名后缀匹配开关 (#929)

* feat: 支持创建邮箱 API 的子域名后缀匹配开关 * fix: 修复 review 提到的开关三态与域名校验问题 * fix: 补充域名归一化与子域名匹配回归测试 * fix: 修复后台开关跟随 env 回退与 account_settings 半成功保存 * fix: 收口账号设置刷新提示与子域名状态重复读取 * fix: 拦截超长域名并透传账号设置刷新失败
2026-09-05 23:47:50 +08:00 · 2026-04-04 00:11:23 +08:00
parent d2c940aa2c
commit 1a7cfb8c95
21 changed files with 776 additions and 23 deletions
@@ -39,6 +39,32 @@ res = requests.post(
 print(res.json())
 ```

+### Create a Subdomain Mailbox Address
+
+If your base domain is already configured in `DOMAINS` / `DEFAULT_DOMAINS` / `USER_ROLES`, and
+`ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` is enabled (it can also be toggled in the admin panel),
+the create-address APIs can accept subdomains directly:
+
+```python
+res = requests.post(
+    "https://xxxx.xxxx/admin/new_address",
+    json={
+        "enablePrefix": True,
+        "name": "project001",
+        "domain": "team.example.com",
+    },
+    headers={
+        'x-admin-auth': "<your_website_admin_password>",
+        "Content-Type": "application/json"
+    }
+)
+```
+
+- If `example.com` is an allowed base domain, `team.example.com` and `dev.team.example.com` can match successfully
+- Lookalike domains such as `badexample.com` will **not** be treated as `example.com`
+- This is different from `RANDOM_SUBDOMAIN_DOMAINS`: here the caller **explicitly specifies** the subdomain, instead of the system generating a random one
+- In the admin panel, this can be set to **Follow Environment Variable / Force Enable / Force Disable**. Choosing **Follow Environment Variable** clears the admin override and returns to env fallback behavior.
+
 ## Batch Create Random Username Email Addresses API Example

 ### Batch Create Email Addresses via Admin API
@@ -35,3 +35,24 @@ RANDOM_SUBDOMAIN_LENGTH = 8
 >
 > It does not automatically create Cloudflare-side subdomain mail routes or DNS records for you,
 > so make sure the base-domain/subdomain routing is already available first.
+
+## Let APIs Specify Subdomains Directly
+
+If you do not want the system to generate a random subdomain, and instead want the caller to
+explicitly create addresses like `team.abc.com`, enable:
+
+```toml
+ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH = true
+```
+
+When this is enabled, as long as `abc.com` is in the allowed base-domain list, the following
+addresses can be created through `/api/new_address` or `/admin/new_address`:
+
+- `name@team.abc.com`
+- `name@dev.team.abc.com`
+
+> [!NOTE]
+> This only relaxes the domain validation used by the create-address APIs. It does not change the
+> default domain dropdown, and it does not create Cloudflare-side subdomain mail routes for you.
+>
+> If the admin panel has already saved an override once, you can switch it back to **Follow Environment Variable** to clear the override and return to env fallback behavior.
@@ -32,6 +32,7 @@
 | `ADDRESS_REGEX`                       | Text      | Regular expression to replace illegal symbols in `email address` name, symbols not in the regex will be replaced. Default is `[^a-z0-9]` if not set. Use with caution as some symbols may prevent email reception | `[^a-z0-9]`                               |
 | `DEFAULT_DOMAINS`                     | JSON      | Default domains available to users (not logged in or users without assigned roles)                                                                                                                                | `["awsl.uk", "dreamhunter2333.xyz"]`      |
 | `CREATE_ADDRESS_DEFAULT_DOMAIN_FIRST` | Text/JSON | Whether to prioritize default domain when creating new addresses, if set to true, will use the first domain when no domain is specified, mainly for telegram bot scenarios                                        | `false`                                   |
+| `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` | Text/JSON | Whether to 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` | `true` |
 | `RANDOM_SUBDOMAIN_DOMAINS`            | JSON      | Base domains that allow optional random subdomain creation, so `name@abc.com` can become `name@<random>.abc.com`                                                                                                   | `["abc.com"]`                             |
 | `RANDOM_SUBDOMAIN_LENGTH`             | Number    | Random subdomain length, default `8`, valid range `1-63`                                                                                                                                                           | `8`                                       |
 | `DOMAIN_LABELS`                       | JSON      | For Chinese domains, you can use DOMAIN_LABELS to display Chinese names                                                                                                                                           | `["中文.awsl.uk", "dreamhunter2333.xyz"]` |
@@ -45,6 +46,18 @@
 >
 > Subdomain addresses are usually best used for receiving only; for sending, prefer the main
 > domain.
+>
+> `ENABLE_CREATE_ADDRESS_SUBDOMAIN_MATCH` is different from random subdomain generation: it lets
+> API callers **directly specify** a subdomain such as `foo.example.com`, while random subdomain
+> generation appends one automatically during creation.
+>
+> `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.

 ## Email Reception Related Variables