飞书开放平台 Server API 文档

主题

获取邮件详情 ​

获取邮件详情

Tip: 使用应用权限访问时，需要申请邮件数据资源的数据权限。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/messages/:message_id
HTTP MethodGET
接口频率限制100 次/分钟
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用mail:user_mailbox.message:readonly 查询用户邮件
字段权限要求> Tip: 该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请 mail:user_mailbox.message.address:read 获取邮件内容中地址相关字段 mail:user_mailbox.message.body:read 获取邮件正文 mail:user_mailbox.message.subject:read 获取邮件主题

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

路径参数 ​

名称类型描述
user_mailbox_idstring用户邮箱地址 或 输入me代表当前调用接口用户
示例值："user@xxx.xx 或 me"
message_idstring用户邮件 id，获取方式见 列出邮件
示例值："TUlHc1NoWFhJMXgyUi9VZTNVL3h6UnlkRUdzPQ=="

查询参数 ​

名称类型必填描述
formatstring否需要获取的邮件内容。支持选择full/plain_text_full/metadata
示例值：full
可选值有：
- full: 全文，包括标签、文件夹、主题、收发件人、纯文本、HTML等信息 - plain_text_full: 全文，只返回纯文本正文内容，不返回HTML。返回内容包括标签、文件夹、主题、收发件人、纯文本等信息 - metadata: 邮件元数据信息，包括标签、文件夹、主题、收发件人、摘要等信息，不返回正文内容

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ messagemessage邮件体
    └ subjectstring主题
字段权限要求： mail:user_mailbox.message.subject:read 获取邮件主题
    └ tomail_address\[\]收件人
字段权限要求： mail:user_mailbox.message.address:read 获取邮件内容中地址相关字段
      └ mail_addressstring邮件地址
      └ namestring名称
    └ ccmail_address\[\]抄送
字段权限要求： mail:user_mailbox.message.address:read 获取邮件内容中地址相关字段
      └ mail_addressstring邮件地址
      └ namestring名称
    └ bccmail_address\[\]密送
字段权限要求： mail:user_mailbox.message.address:read 获取邮件内容中地址相关字段
      └ mail_addressstring邮件地址
      └ namestring名称
    └ head_frommail_address发件人
字段权限要求： mail:user_mailbox.message.address:read 获取邮件内容中地址相关字段
      └ mail_addressstring邮件地址
      └ namestring名称
    └ body_htmlstring正文(base64url)
字段权限要求： mail:user_mailbox.message.body:read 获取邮件正文
    └ internal_datestring创建/收/发信时间（毫秒）
    └ message_stateint邮件状态，1为收信，2为发信，3为草稿
    └ smtp_message_idstringRFC协议id
    └ message_idstring邮件id
    └ attachmentsattachment\[\]邮件附件列表
字段权限要求： mail:user_mailbox.message.body:read 获取邮件正文
      └ filenamestring附件文件名
      └ idstring附件 id
      └ attachment_typeint附件类型
可选值有：
- 1: 普通附件 - 2: 超大附件
      └ is_inlineboolean是否为内联图片，true 表示是内联图片
      └ cidstring内容 ID，HTML 中通过 cid: 协议引用该图片
    └ body_plain_textstring正文纯文本(base64url)
字段权限要求： mail:user_mailbox.message.body:read 获取邮件正文
    └ thread_idstring会话id
    └ body_previewstring邮件正文纯文本内容的前100个字符，基于base64url编码，用于快速预览邮件核心内容，无需解码完整正文
    └ label_idsstring\[\]标签ID
    └ folder_idstring文件夹ID
    └ in_reply_tostringIn-Reply-To邮件头
    └ reply_tostringReply-To邮件头
    └ priority_typestring邮件优先级
可选值有：
- 0: 无优先级 - 1: 高优先级 - 3: 正常优先级 - 5: 低优先级
    └ security_levelsecurity_level安全信息
      └ is_riskboolean是否风险邮件
      └ risk_banner_levelstring风险邮件等级
可选值有：
- WARNING: 警告 - DANGER: 危险 - INFO: 提示
      └ risk_banner_reasonstring风险邮件原因
可选值有：
- NO_REASON: 未知 - IMPERSONATE_DOMAIN: 相似域名仿冒 - IMPERSONATE_KP_NAME: KP姓名仿冒 - UNAUTH_EXTERNAL: 未认证外部域名 - MALICIOUS_URL: 恶意链接 - MALICIOUS_ATTACHMENT: 高危附件 - PHISHING: 钓鱼邮件 - IMPERSONATE_PARTNER: 仿冒合作伙伴 - EXTERNAL_ENCRYPTION_ATTACHMENT: 外部邮件携带加密附件
      └ is_header_from_externalboolean发件人是否外部邮件
      └ via_domainstring代发或伪造邮件展示SPF或DKIM域名
      └ spam_banner_typestring垃圾邮件原因
可选值有：
- USER_REPORT: 用户曾标记邮件是垃圾邮件 - USER_BLOCK: 用户曾将发件人的邮件标记为垃圾邮件 - ANTI_SPAM: 系统判为垃圾邮件 - USER_RULE: 命中收信规则进入垃圾邮件 - BLOCK_DOMIN: 用户已拦截来自该域名的邮件 - BLOCK_ADDRESS: 用户已拦截来自该邮件地址的邮件
      └ spam_user_rule_idstring命中的收信规则ID
      └ spam_banner_infostring命中用户黑名单的地址或域名信息
    └ referencesstringReferences邮件头

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "message": {
            "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": [
                {
                    "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": true,
                "risk_banner_level": "1",
                "risk_banner_reason": "101",
                "is_header_from_external": false,
                "via_domain": "larksuite.com",
                "spam_banner_type": "1",
                "spam_user_rule_id": "7618365627924925388",
                "spam_banner_info": "larksuite.com"
            },
            "references": "<5678.abcd@test.com>\r\n\t<1234.abcd@message-id>"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4041235013mailbox not found请检查邮箱地址是否正确
4001234008wrong parameters参数错误，请检查参数格式或取值是否符合接口要求后重试
4041234034message not found请检查邮件 id 是否正确，获取邮件 id 的方式可参考 列出邮件
4031234017permission not granted无权限访问，请确认应用是否具备访问该资源的权限。如使用用户身份访问，请确认具备此用户的访问权限；如使用租户身份访问，请确认已申请对应的数据范围权限。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有