# 撤回已发送的邮件

撤回指定邮件。

前置条件：邮件须已投递，且发送时间在 24 小时以内；搬家中的域名不支持撤回。

返回说明：若用户或邮件不满足撤回条件，接口仍返回 200，响应体中 recall_status 为 unavailable，recall_restriction_reason 标明具体原因。返回成功仅表示撤回请求已受理，实际撤回结果请调用「查询邮件撤回进度」接口获取。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/messages/:message_id/recall
HTTP Method | POST
接口频率限制 | [10 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 修改邮件(mail:user_mailbox.message:modify)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>或<br>`user_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)

### 路径参数

名称 | 类型 | 描述
---|---|---
user_mailbox_id | string | 用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户<br>**示例值**："me"
message_id | string | 需要撤回的邮件ID，即调用接口[发送草稿](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/mail-v1/user_mailbox-draft/send)返回的参数message_id<br>**示例值**："xxx"

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
recall_status | string | 撤回状态。仅当不支持撤回时返回unavailable<br>**可选值有**：<br>- unavailable：邮件不可撤回<br>- available：邮件可撤回
recall_restriction_reason | string | 不支持撤回的原因。仅当recall_status为unavailable时返回<br>**可选值有**：<br>- recall_not_enabled：暂未开放撤回功能<br>- migration_domain：你的地址未使用Lark邮箱服务，无法在Lark内进行撤回<br>- sender_address_not_owned：邮件发件人地址不是用户可用发信地址<br>- already_recalled：邮件已发起锅撤回<br>- not_delivered：未发送的邮件无法撤回<br>- exceeded_time_limit：无法撤回 24 小时前发送的邮件

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "recall_status": "unavailable",
        "recall_restriction_reason": "recall_not_enabled"
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
500 | 1235000 | internal error | 服务器内部错误，请稍后重试
429 | 1234029 | too many request | 请勿并发请求接口，请稍后重试
400 | 1234034 | message not found | 指定邮件不存在，请核对参数后重试
403 | 1230004 | permission denied: mailbox not found, unsupported mailbox type, or no access to this mailbox | 无权限访问：指定邮箱地址不存在，或传入了不支持的邮箱类型，或无权限访问此邮箱。请检查邮箱或权限后重试。