飞书开放平台 Server API 文档

主题

全量更新个人邮件模板 ​

以全量替换的方式更新指定邮件模板的所有字段（包括名称、主题、正文、附件、收件信息等）。本接口为「全量更新」语义：请求时需传入完整的模板对象，未携带的字段将被清空。调用依赖：如仅修改部分字段，请先调用获取个人邮件模板详情接口拿到完整模板，在本地修改后再传回本接口，以避免漏传字段导致数据丢失。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/templates/:template_id
HTTP MethodPUT
接口频率限制5 次/秒
支持的应用类型custom
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用mail:user_mailbox.message:modify 修改邮件

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token
Content-Typestring是固定值："application/json; charset=utf-8"

路径参数 ​

名称类型描述
user_mailbox_idstring用户邮箱地址，作为用户邮箱身份标识。使用 user_access_token 调用时，可使用占位符 me 表示当前授权用户的主邮箱。
示例值："user@example.com"
template_idstring邮件模板 ID。可通过列出个人邮件模板接口或创建个人邮件模板接口的返回值获取。
示例值："7281187859195772947"

请求体 ​

名称类型必填描述
templatetemplate是替换后的完整模板内容（全量替换）
  └ namestring是模板名称，不超过 100 字符
示例值："销售跟进模板"
数据校验规则：
- 长度范围：1 ～ 100 字符
  └ subjectstring否邮件主题，不超过 1000 字符
示例值："关于本周订单跟进"
数据校验规则：
- 最大长度：1000 字符
  └ template_contentstring否模板正文（HTML 或纯文本）。单模板正文大小上限 3 MB（3 * 1024 * 1024 字节），超过将返回错误码 1230006 template content size limit exceeded。
示例值："Hi ${name},"
数据校验规则：
- 最大长度：3145728 字符
  └ is_plain_text_modeboolean否是否为纯文本模式。true 表示模板正文按纯文本渲染，false 表示按 HTML 渲染。默认 false（HTML 模式）。
示例值：false
默认值：false
  └ tosmail_address\[\]否默认收件人地址列表
数据校验规则：
- 长度范围：0 ～ 100
    └ mail_addressstring是邮件地址
示例值："mike@outlook.com"
    └ namestring否名称
示例值："Mike"
  └ ccsmail_address\[\]否默认抄送地址列表
数据校验规则：
- 长度范围：0 ～ 100
    └ mail_addressstring是邮件地址
示例值："mike@outlook.com"
    └ namestring否名称
示例值："Mike"
  └ bccsmail_address\[\]否默认密送地址列表
数据校验规则：
- 长度范围：0 ～ 100
    └ mail_addressstring是邮件地址
示例值："mike@outlook.com"
    └ namestring否名称
示例值："Mike"
  └ attachmentstemplate_attachment\[\]否模板附件与内嵌图片列表
数据校验规则：
- 长度范围：0 ～ 50
    └ filenamestring否附件文件名
示例值："plan.xlsx"
数据校验规则：
- 最大长度：255 字符
    └ idstring否附件 id（Drive file_key，用于引用 Drive medias 上传接口返回的 file_key）
示例值："boxcnrHpsg1QDqXPrJXWPwbqsKh"
    └ attachment_typeint否附件类型
示例值：1
可选值有：
- 1: 普通附件 - 2: 超大附件
数据校验规则：
- 取值范围：1 ～ 2
    └ is_inlineboolean否是否为内联图片，true 表示是内联图片
示例值：false
默认值：false
    └ cidstring否内容 ID，HTML 中通过 cid: 协议引用该图片
示例值："image1@example.com"
数据校验规则：
- 最大长度：255 字符

请求体示例 ​

json
{
    "template": {
        "name": "销售跟进模板",
        "subject": "关于本周订单跟进",
        "template_content": "Hi ${name},",
        "is_plain_text_mode": false,
        "tos": [
            {
                "mail_address": "mike@outlook.com",
                "name": "Mike"
            }
        ],
        "ccs": [
            {
                "mail_address": "mike@outlook.com",
                "name": "Mike"
            }
        ],
        "bccs": [
            {
                "mail_address": "mike@outlook.com",
                "name": "Mike"
            }
        ],
        "attachments": [
            {
                "filename": "plan.xlsx",
                "id": "boxcnrHpsg1QDqXPrJXWPwbqsKh",
                "attachment_type": 1,
                "is_inline": false,
                "cid": "image1@example.com"
            }
        ]
    }
}

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ templatetemplate更新后的模板
    └ template_idstring模板 id
    └ namestring模板名称，不超过 100 字符
    └ subjectstring邮件主题，不超过 1000 字符
    └ template_contentstring模板正文（HTML 或纯文本）。单模板正文大小上限 3 MB（3 * 1024 * 1024 字节），超过将返回错误码 1230006 template content size limit exceeded。
    └ is_plain_text_modeboolean是否为纯文本模式。true 表示模板正文按纯文本渲染，false 表示按 HTML 渲染。默认 false（HTML 模式）。
    └ tosmail_address\[\]默认收件人地址列表
      └ mail_addressstring邮件地址
      └ namestring名称
    └ ccsmail_address\[\]默认抄送地址列表
      └ mail_addressstring邮件地址
      └ namestring名称
    └ bccsmail_address\[\]默认密送地址列表
      └ mail_addressstring邮件地址
      └ namestring名称
    └ attachmentstemplate_attachment\[\]模板附件与内嵌图片列表
      └ filenamestring附件文件名
      └ idstring附件 id（Drive file_key，用于引用 Drive medias 上传接口返回的 file_key）
      └ attachment_typeint附件类型
可选值有：
- 1: 普通附件 - 2: 超大附件
      └ is_inlineboolean是否为内联图片，true 表示是内联图片
      └ cidstring内容 ID，HTML 中通过 cid: 协议引用该图片
    └ create_timestring模板创建时间（毫秒级时间戳字符串，避免 JS 弱类型侧 i64 精度丢失）

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "template": {
            "template_id": "7281187859195772947",
            "name": "销售跟进模板",
            "subject": "关于本周订单跟进",
            "template_content": "Hi ${name},",
            "is_plain_text_mode": false,
            "tos": [
                {
                    "mail_address": "mike@outlook.com",
                    "name": "Mike"
                }
            ],
            "ccs": [
                {
                    "mail_address": "mike@outlook.com",
                    "name": "Mike"
                }
            ],
            "bccs": [
                {
                    "mail_address": "mike@outlook.com",
                    "name": "Mike"
                }
            ],
            "attachments": [
                {
                    "filename": "plan.xlsx",
                    "id": "boxcnrHpsg1QDqXPrJXWPwbqsKh",
                    "attachment_type": 1,
                    "is_inline": false,
                    "cid": "image1@example.com"
                }
            ],
            "create_time": "1716279320000"
        }
    }
}

错误码 ​

HTTP状态码错误码描述排查建议
4001230001param invalid请根据错误信息「param invalid」核查请求参数后重试。
5001230003internal server error服务端异常（1230003 internal server error）。可稍后重试，或携带 request id 联系接口负责人。
4031230002permission deny权限不足（1230002 permission deny）。请确认 access_token 已开通该接口所需的 scope。
4001230004invalid template name请根据错误信息「invalid template name」核查请求参数后重试。
4001230006template content size limit exceeded请根据错误信息「template content size limit exceeded」核查请求参数后重试。
4041230007template not found资源不存在（1230007 template not found）。请核对路径参数是否指向真实存在的资源。
4001230008template total size limit exceeded请根据错误信息「template total size limit exceeded」核查请求参数后重试。
4001230009invalid template param请根据错误信息「invalid template param」核查请求参数后重试。
4031230011template attachment forbidden权限不足（1230011 template attachment forbidden）。请确认 access_token 已开通该接口所需的 scope。

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

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