# 批量获取邮件详情
通过指定邮件ID，获取对应邮件的标签、文件夹、摘要、正文、html、附件等信息。
**注意事项**：注意，如需获取摘要、正文、主题或收发件人地址，需要申请对应的字段权限。
## 请求
基本 |
---|---
HTTP URL | https://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/messages/batch_get
HTTP Method | POST
接口频率限制 | [10 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App
权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用** | 查询用户邮件(mail:user_mailbox.message:readonly)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
获取邮件正文(mail:user_mailbox.message.body:read)
获取邮件主题(mail:user_mailbox.message.subject:read)
### 请求头
名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`
或
`user_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer u-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)
Content-Type | string | 是 | **固定值**："application/json; charset=utf-8"
### 路径参数
名称 | 类型 | 描述
---|---|---
user_mailbox_id | string | 用户邮箱地址。当使用用户身份访问时，可以输入"me"代表当前调用接口用户
**示例值**："me"
### 请求体
名称 | 类型 | 必填 | 描述
---|---|---|---
format | string | 否 | 需要获取的邮件内容
**示例值**："full"
**可选值有**：
- full：全文，包括标签、文件夹、主题、收发件人、纯文本、HTML等信息
- plain_text_full：全文，只返回纯文本正文内容，不返回HTML。返回内容包括标签、文件夹、主题、收发件人、纯文本等信息
- metadata：邮件元数据信息，包括标签、文件夹、主题、收发件人、摘要等信息，不返回正文内容
message_ids | string\[\] | 否 | 需要的邮件ID，可以通过列出邮件列表、收信事件通知等方式获得
**示例值**：["xxx"]
**数据校验规则**：
- 长度范围：`0` ～ `20`
### 请求体示例
```json
{
"format": "full",
"message_ids": [
"xxx"
]
}
```
## 响应
### 响应体
名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
messages | message\[\] | 返回邮件内容
raw | string | MIME邮件数据，基于base64url编码
subject | string | 主题
**字段权限要求**：
获取邮件主题(mail:user_mailbox.message.subject:read)
to | mail_address\[\] | 收件人
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
cc | mail_address\[\] | 抄送
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
bcc | mail_address\[\] | 密送
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
head_from | mail_address | 发件人
**字段权限要求**：
获取邮件内容中地址相关字段(mail:user_mailbox.message.address:read)
mail_address | string | 邮件地址
name | string | 名称
body_html | string | 正文(base64url)
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
internal_date | string | 创建/收/发信时间（毫秒）
message_state | int | 邮件状态，1（收信）2（发信）3（草稿）
smtp_message_id | string | RFC协议id
message_id | string | 邮件id
attachments | attachment\[\] | 邮件附件列表
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
body | string | 附件的正文，使用 base64url 编码（支持的文件最大 37MB）
filename | string | 附件文件名
id | string | 附件 id
attachment_type | int | 附件类型
**可选值有**：
- 1：普通附件
- 2：超大附件
is_inline | boolean | 是否为内联图片，true 表示是内联图片
cid | string | 内容 ID，HTML 中通过 cid: 协议引用该图片
body_plain_text | string | 正文纯文本(base64url)
**字段权限要求**：
获取邮件正文(mail:user_mailbox.message.body:read)
thread_id | string | 会话id
body_preview | string | 邮件正文纯文本内容的前100个字符，基于base64url编码，用于快速预览邮件核心内容，无需解码完整正文
label_ids | string\[\] | 标签ID
folder_id | string | 文件夹ID
in_reply_to | string | In-Reply-To邮件头
reply_to | string | Reply-To邮件头
priority_type | string | 邮件优先级
**可选值有**：
- 0：无优先级
- 1：高优先级
- 3：正常优先级
- 5：低优先级
security_level | security_level | 安全信息
is_risk | boolean | 是否风险邮件
risk_banner_level | string | 风险邮件等级
**可选值有**：
- WARNING：警告
- DANGER：危险
- INFO：提示
risk_banner_reason | string | 风险邮件原因
**可选值有**：
- NO_REASON：未知
- IMPERSONATE_DOMAIN：相似域名仿冒
- IMPERSONATE_KP_NAME：KP姓名仿冒
- UNAUTH_EXTERNAL：未认证外部域名
- MALICIOUS_URL：恶意链接
- MALICIOUS_ATTACHMENT：高危附件
- PHISHING：钓鱼邮件
- IMPERSONATE_PARTNER：仿冒合作伙伴
- EXTERNAL_ENCRYPTION_ATTACHMENT：外部邮件携带加密附件
is_header_from_external | boolean | 发件人是否外部邮件
via_domain | string | 代发或伪造邮件展示SPF或DKIM域名
spam_banner_type | string | 垃圾邮件原因
**可选值有**：
- USER_REPORT：用户曾标记邮件是垃圾邮件
- USER_BLOCK：用户曾将发件人的邮件标记为垃圾邮件
- ANTI_SPAM：系统判为垃圾邮件
- USER_RULE：命中收信规则进入垃圾邮件
- BLOCK_DOMIN：用户已拦截来自该域名的邮件
- BLOCK_ADDRESS：用户已拦截来自该邮件地址的邮件
spam_user_rule_id | string | 命中的收信规则ID
spam_banner_info | string | 命中用户黑名单的地址或域名信息
references | string | References邮件头
### 响应体示例
```json
{
"code": 0,
"msg": "success",
"data": {
"messages": [
{
"raw": "Q29udGVudC1UeXBlOiB0ZXh0L3BsYWluOyBjaGFyc2V0PSJ1cy1hc2NpaSIKTUlNRS1WZXJzaW9uOiAxLjAKQ29udGVudC1UcmFuc2Zlci1FbmNvZGluZzogN2JpdAp0bzogInRvIiA8dG9AeHh4Lnh4Pgpmcm9tOiAiZnJvbSIgPGZyb21AeHh4Lnh4PgpzdWJqZWN0OiB0aGlzIGlzIGEgc3ViamVjdAoKdGhpcyBpcyB0aGUgbWVzc2FnZSBib2R5Lg",
"subject": "邮件标题",
"to": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"cc": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"bcc": [
{
"mail_address": "mike@outlook.com",
"name": "Mike"
}
],
"head_from": {
"mail_address": "mike@outlook.com",
"name": "Mike"
},
"body_html": "xxxx",
"internal_date": "1682377086000",
"message_state": 1,
"smtp_message_id": "ay0azrJDvbs3FJAg@outlook.com",
"message_id": "tfuh9N4WnzU6jdDw=",
"attachments": [
{
"body": "aGVsbG8gd29ybGQK",
"filename": "helloworld.txt",
"id": "YQqYbQHoQoDqXjxWKhJbo8Gicjf",
"attachment_type": 1,
"is_inline": false,
"cid": "image1@example.com"
}
],
"body_plain_text": "xxxxx",
"thread_id": "tfuh9N4WnzU6jdDw=",
"body_preview": "xxxxx",
"label_ids": [
"FLAGGED"
],
"folder_id": "INBOX",
"in_reply_to": "06d20.dbf451a3.808a.475a.acc9.1363dfd20f36@larksuite.com",
"reply_to": "06d20.dbf451a3.808a.475a.acc9.1363dfd20f36@larksuite.com",
"priority_type": "0",
"security_level": {
"is_risk": false,
"risk_banner_level": "WARNING",
"risk_banner_reason": "IMPERSONATE_DOMAIN",
"is_header_from_external": false,
"via_domain": "larksuite.com",
"spam_banner_type": "USER_REPORT",
"spam_user_rule_id": "7618365627924925388",
"spam_banner_info": "larksuite.com"
},
"references": "<5678.abcd@test.com>\r\n\t<1234.abcd@message-id>"
}
]
}
}
```
### 错误码
HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 1230001 | param is invalid | 参数错误，请检查请求参数的类型、格式或值是否与接口要求一致，具体可参考接口文档中的参数说明
400 | 1230003 | user mailbox not found | 用户邮箱地址不存在，请检查输入的用户邮箱地址是否正确，或确认用户的邮箱处于正常状态
500 | 1230004 | internal error | 内部服务错误，请稍后重试
403 | 1230005 | permission not granted | 无权限访问，请确认应用是否具备访问该资源的权限。如使用用户身份访问，请确认具备此用户的访问权限；如使用租户身份访问，请确认已申请对应的数据范围权限。
400 | 1230006 | message not found | 指定邮件不存在，请核对邮件ID，邮件ID可通过列出邮件列表等接口获得