Email Account

Email Account 是注册到某个 Space 的 SMTP 发件人。它是把发信服务器地址、登录信息以及发信地址打包保存在一起的资源。当 Script 的 EmailSend statement 执行时，实际的邮件就通过这个 Email Account 发出。例如，服装店商城想在每次收到订单时发送确认邮件，就要先注册好用于发送的 Email Account，再让 Script 引用它。

Email Account 是由 CMA 管理的 Space 下级资源，路径以 /spaces/{spaceId}/email-accounts 为基准。它没有发布（publish）概念。没有状态值或发布阶段，创建后即可立即用于发送。不过，创建并不是无害的只读式操作，而是实际发送一封邮件来验证配置的操作；而且连接信息（endpoint·username·password）一旦创建就无法更改。这些将在下文说明。

资源结构

以下是创建 Email Account 时的响应。sys（系统属性）中包含标识符与版本，正文中包含发件人配置（name·endpoint·username·fromAddress·fromName）。密码（password）不会出现在响应的任何位置。

{
  "sys": {
    "id": "3trmXRMdKpLc7GfNbyVQeR2WsT9LnU",
    "type": "EmailAccount",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-04T05:12:44.108Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-04T05:12:44.108Z",
    "version": 1
  },
  "name": "订单通知发送",
  "endpoint": {
    "host": "smtp.gmail.com",
    "port": 587,
    "security": "StartTls"
  },
  "username": "orders@example-shop.com",
  "fromAddress": "orders@example-shop.com",
  "fromName": "服装店订单"
}

主要键：

• sys.id：Email Account 的唯一标识符。用于单条查询·修改·删除路径中的 {emailAccountId}。
• sys.version：资源版本。从 1 开始，每次修改时递增。修改请求时把该值放在 X-Weegloo-Version 头中发送（参见下文 状态与约束）。
• name：显示在控制台上的标签（例如 订单通知发送）。不用于发送，也不是 From 显示名。 它只是用于区分多个发件人的名称。
• endpoint：要连接的 SMTP 服务器。由 host·port·security 三个值组成。
• username：SMTP 登录用户名。因服务商而异。可能就是邮件地址本身，也可能是发送服务规定的固定字符串或按域名的登录名。
• fromAddress：发信地址。既是发出信封的退信处（MAIL FROM），也同时作为收件人看到的 From 地址使用。
• fromName：显示在 From 头中的显示名（可选）。缺省时只显示地址。

密码（password）是只在创建请求正文中发送的只写值，因此既不会出现在上面的响应中，也不会在之后的查询·列表中返回。username 在查询响应中会原样返回输入的值。

系统属性 (sys)

每个 Email Account 都在 sys 对象中包含公共系统属性。space、createdBy、updatedBy 以 Refer 形态（{ "sys": { "id", "type": "Refer", "targetType" } }）呈现。

正文属性：

仅用于创建请求正文的输入：

发件人信息与连接信息

Email Account 的值分为两类。这一区分决定了哪些可以修改。

• 连接信息 — endpoint·username·password。 创建后无法更改。要更换发信服务器或轮换登录信息时，新建一个 Email Account 并删除原有的。密码如上文所述无法再次读取，因此若丢失，不是重置而是按重新创建处理。
• 发件人信息 — name·fromAddress·fromName。 创建后仍可通过修改（PUT）更改。用于整理标签或更改发信地址·显示名，此时连接信息保持不变。

创建时会实际发送邮件

Email Account 的创建不是只保存配置的操作。在保存之前，服务器会用输入的 endpoint·username·password 实际连接并发送一封测试邮件。 发送对象是 fromAddress，若 username 是其他地址，也可能包含该地址。

• 只有发送成功，资源才会被保存。
• 服务器在连接·认证·发送的任一阶段拒绝时，什么都不会创建并失败，响应中会一并包含服务器返回的失败原因。

因此需注意：用错误的值反复创建，每次都会实际尝试发送。

状态与约束

创建·修改时需遵守的值约束。

关于行为与权限的规则：

• 连接信息不可变。 Update（PUT）可更改的只有 name·fromAddress·fromName。要更改 endpoint·username·password，需新建并删除原有的。
• 修改需要版本。 Update 请求中把当前 sys.version 值放在 X-Weegloo-Version 头中发送。若值不是最新的，会因版本冲突被拒绝。此时重新查询资源，用最新的 sys.version 重试。
• 密码无法再次读取。 查询·列表的任何位置都不会出现，因此丢失时不是重置而是按重新创建处理。
• 可用的 SMTP 服务器因方案而异。 以预设形式提供的服务商主机（Gmail·Naver·Resend·Brevo）在较低方案中也可注册。预设中没有的任意（自托管）主机需要已登记付款方式才能使用。各方案的策略请参阅 定价方案。

API

以下所有端点的基准 URL 为 https://cma.weegloo.com/v1，Authorization 头中需要认证 CMA 的 Bearer 令牌。修改（PUT）额外需要 X-Weegloo-Version 头。

相关文档

• Script：用 EmailSend statement 通过这个 Email Account 发送邮件。
• SpaceRole：定义该 Space 资源访问权限的角色。
• 定价方案：预设服务商主机与任意（自托管）SMTP 主机的使用策略。