mipu-open/docs/11-02_mailbox-domain-apply.md

mailbox/domain/apply - 申请绑定域名

申请绑定域名(mailbox/domain/apply) API 说明文档

使用场景

1. 企业客户需要为自己的邮箱系统绑定自定义域名
2. 配置企业邮箱后，员工可以使用 @company.com 格式的邮箱地址

错误场景(不应该使用本接口的场景)

1. 域名已被其他客户绑定
2. 域名格式不正确（如包含非法字符）
3. 客户已达到域名绑定数量上限

性能指标

• 响应速度：98% 的请求响应速度 < 1000ms

请求说明

请求地址	https://${endpoint}/mailbox/domain/apply
请求方法	POST

请求参数

Header

参数名称	类型	是否必选	示例值	说明
Content-Type	String	是	application/json	固定值，指定请求体格式为 JSON
Accept-Encoding	String	是	gzip, deflate, br	必须要填写，否则服务器会拒绝
client-key	String	是	xxxxx	联系我们获取生产环境key
client-secret	String	是	xxxxx	联系我们获取生产环境secret

请求体

{
  "domainName": "example.com"
}

参数详情

参数名称	类型	是否必选	示例值	说明
domainName	String	是	example.com	要绑定的域名名称，必须是有效的域名格式

返回参数

参数名称	类型	示例值	说明
domainId	Long	123	域名唯一标识
domainName	String	example.com	域名名称
status	String	PENDING	域名状态：PENDING=待DNS验证
dnsVerified	Boolean	false	DNS验证状态，新申请的域名需要验证
createTime	String	2025-01-02T10:00:00Z	域名创建时间（ISO 8601格式）

返回示例

{
  "domainId": 123,
  "domainName": "example.com",
  "status": "PENDING",
  "dnsVerified": false,
  "createTime": "2025-01-02T10:00:00Z"
}

后续步骤

申请域名绑定后，需要完成DNS验证才能激活邮箱服务：

1. 在域名DNS管理中添加相应的MX记录
2. 调用 mailbox/domain/verify 接口验证DNS配置
3. 验证通过后，域名状态将变为 ACTIVE

错误码说明

错误码	说明
400	请求参数错误，域名格式不正确
401	认证失败，client-key 或 client-secret 无效
409	域名已被其他客户绑定
429	已达到域名绑定数量上限
500	服务器内部错误