阿里邮箱 API 开放平台

阿里邮箱 API 开放平台用于把企业邮箱能力接入企业自有系统和自动化脚本。它覆盖组织、域名、用户、部门、邮件组、公共联系人、邮件、日历、登录、审计日志、文件流、隔离区和规则等能力，适合做账号生命周期管理、组织同步、邮件和日历自动化、安全审计、隔离区处置、企业内部运营工具和批量脚本。

免费版阿里邮箱不支持 API 开放平台。使用前需要企业管理员在域管控制台启用应用、分配 API 权限，并妥善保管应用凭证。

接入模型

在域管控制台进入高级应用或 API 开放平台，创建应用。
为应用授予最小必要权限，例如 User.ReadWrite.All、Department.Read.All、Mail.Read.All、Mail.Send.All、Calendar.ReadWrite.All。
获取应用的 client_id 和 client_secret，通过 OAuth2 client credentials 流程换取访问令牌。
调用接口时在请求头携带 Authorization: Bearer <access_token>。
按企业所在地域和当前环境使用接口页面给出的 Base URL：https://alimail-cn.aliyuncs.com。不要跨集群复用地址。

获取访问凭证

授权 Token 获取

调用邮箱 API 之前，需要先在邮箱域管中的 API 开放平台创建应用、分配权限，之后可以使用应用的 client_id 和 client_secret 调用授权接口，换取授权 Token。授权接口请求方法如下：

POST /oauth2/v2.0/token HTTP/1.1
Host: alimail-cn.aliyuncs.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

请求参数说明：

参数名	必填	说明
`grant_type`	Y	固定取值：`client_credentials`。
`client_id`	Y	请求授权 Token 的应用 ID，由邮箱企业管理员在后台注册应用后获取。
`client_secret`	Y	请求授权 Token 的应用 Secret，由邮箱企业管理员在后台注册应用后获取。请勿对外泄漏，任何人拥有应用 ID 和 Secret 后都能够以该应用的身份调用 API。

返回参数说明：

参数名	说明
`token_type`	Token 类型，目前统一为 `bearer`。
`access_token`	授权 Token。
`expires_in`	授权 Token 有效时间，单位为秒。建议调用方缓存授权 Token，并在过期后重新获取。

请求示例（curl）：

curl -X POST \
  'https://alimail-cn.aliyuncs.com/oauth2/v2.0/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

请求示例（Java，依赖 OkHttpClient）：

OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(
    mediaType,
    "grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>"
);
Request request = new Request.Builder()
    .url("https://alimail-cn.aliyuncs.com/oauth2/v2.0/token")
    .post(body)
    .addHeader("Content-Type", "application/x-www-form-urlencoded")
    .build();
Response response = client.newCall(request).execute();

返回示例：

{
  "token_type": "bearer",
  "access_token": "...",
  "expires_in": 172799
}

API 调用授权 Token 传递

所有开放 API 调用都需要通过 HTTP 请求头 Authorization 携带有效的授权 Token。请求头的值需要在 Token 前加上 Bearer 前缀。

请求示例：

curl -X POST \
  'https://alimail-cn.aliyuncs.com/...' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  ...

API 访问流量限制

单个域内所有应用的 API 访问流量总计不能超过 40 次/秒。访问流量超出限制后，接口会返回 HTTP status 429。

关键概念

概念	定义
组织	企业邮箱租户的顶层资源。组织下包含域名、用户、部门、邮件组和公共联系人等资源。
域名	企业邮箱收发信的域名。域名相关接口用于创建、查询、验证和管理企业域名。
用户	邮箱账号。用户接口覆盖创建账号、更新资料、重置密码、别名、安全手机、邮箱设置和共享成员等操作。
部门	企业组织架构节点。通常从根部门开始递归查询子部门和部门成员。
邮件组	群组地址和成员集合，用于统一收发、分发和权限控制。
公共联系人	企业通讯录中的共享联系人和分组，区别于个人联系人。
邮件	邮件文件夹、邮件列表、邮件详情、附件、草稿、发送、移动、删除和批量更新等能力。
日历	日历、日程、共享、导入导出和会议回复等能力。
隔离区	位于收件箱与垃圾箱、删除之间的临时容器，用于存放被反垃圾、反病毒或反钓鱼规则拦截的邮件。隔离邮件通常只保留 30 天。
文件流	附件和大文件相关的上传、下载、分片或跳转能力。
Scope	应用权限范围。接口页会列出所需 scope，请按接口要求申请，不要用过大的权限替代。
Cursor	游标式分页标记。列表类接口通常返回下一页游标，调用方需要循环读取直到没有下一页。

主要能力

组织与域名：读取组织信息，更新组织设置，新增、查询、验证和删除域名。
用户与部门：创建账号，修改账号资料，重置密码，管理账号别名、安全手机、邮箱设置、共享关系，递归同步部门树和成员。
邮件组与公共联系人：管理邮件组、成员、公共联系人和公共联系人分组。
邮件：列出邮件文件夹和邮件，读取邮件详情，创建草稿，上传附件，发送草稿，移动、复制、删除和批量更新邮件。
日历：管理日历、日程、共享日历，导入导出事件，处理会议邀请。
安全与治理：查询审计日志，处理隔离区邮件，维护收信黑白名单和相关规则。
登录与文件流：生成免登链接、失效登录令牌，处理附件上传下载和文件流。

常见工作流

创建账号并同步组织架构

查询或创建部门，保存部门 ID。
调用用户创建接口，传入邮箱地址、姓名、部门、密码策略等字段。
如果需要别名、安全手机或邮箱设置，继续调用对应的用户扩展接口。
批量同步时按部门树分批处理，避免把组织架构和用户账号写入顺序混淆。

获取完整部门树

先获取根部门 ID。部分接口可以使用 $root 表示根部门。
调用列出子部门接口。
对每个子部门递归调用，直到没有子节点。
如果接口返回分页字段，按响应中的游标或分页参数继续读取。

读取邮件和附件

选择用户邮箱和邮件文件夹。
调用邮件列表接口，按 cursor、size、排序字段和时间范围分页读取。
调用邮件详情接口获取正文、收发件人和基础元数据。
调用附件列表接口获取附件 ID。
创建附件下载会话，再按返回的下载地址或文件流规则读取附件内容。

创建草稿并发送邮件

企业邮箱 API 的发信流程通常是先创建草稿，再发送草稿。这个能力适合与用户邮箱强相关的特殊业务场景。大规模系统通知、营销邮件或批量外发建议使用阿里云邮件推送等专门产品。

创建草稿，填写收件人、主题、正文和附件信息。
如需附件，先创建上传会话并完成上传。
调用发送草稿接口。
根据响应和审计日志确认发送结果。

处理隔离区邮件

隔离区用于承接被安全策略拦截的邮件。常见动作包括查询隔离邮件、查看邮件详情、列出附件、释放邮件到收件箱、删除邮件，以及维护黑白名单。黑名单通常直接删除命中邮件，白名单通常允许命中邮件直接投递，因此规则变更前要确认范围和优先级。

请求与响应约定

默认使用 JSON 请求体和 JSON 响应体，文件流接口除外。
路径参数、查询参数和 Body 参数以接口页面为准。
所有业务接口都需要 Authorization: Bearer <access_token>。
401 通常表示 token 缺失、错误或过期。
403 通常表示应用没有对应 API 权限，需要在域管应用管理页补充授权。
429 表示触发限流。单个域内所有应用的 API 访问流量总计不能超过 40 次/秒。
400、404、409 等错误通常会包含 detailErrorCode 和 message，处理脚本应该优先读取这两个字段，而不是只判断 HTTP status。
列表接口要关注 cursor、nextCursor、hasMore、size 等分页字段，避免只读取第一页。

安全建议

使用最小权限 scope，按应用职责拆分权限。
不要把 client_secret、access token、用户密码、附件下载地址写入日志。
token 应缓存到过期时间前，过期后重新换取；不要为每个业务请求都重新申请 token。
生产脚本需要有重试、限流、幂等和审计记录。
对删除、批量修改、释放隔离邮件、发送邮件等高风险操作增加人工确认或灰度范围。

接入模型​

获取访问凭证​

授权 Token 获取​

API 调用授权 Token 传递​

API 访问流量限制​

关键概念​

主要能力​

常见工作流​

创建账号并同步组织架构​

获取完整部门树​

读取邮件和附件​

创建草稿并发送邮件​

处理隔离区邮件​

请求与响应约定​

安全建议​

官方参考​