飞书开放平台 Server API 文档

主题

创建个人邮件模板 ​

在指定用户邮箱下创建一份可复用的个人邮件模板。请求时需传入完整的模板对象（含名称、主题、正文、收件信息、附件等），创建成功后返回完整模板内容（含系统生成的 template_id），适用于将常用邮件内容沉淀为模板以便后续快速发送同类型邮件。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/mail/v1/user_mailboxes/:user_mailbox_id/templates
HTTP MethodPOST
接口频率限制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"

请求体 ​

名称类型必填描述
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」核查请求参数后重试。
4001230005template number limit exceeded请根据错误信息「template number limit exceeded」核查请求参数后重试。
4001230006template content size limit exceeded请根据错误信息「template content size limit exceeded」核查请求参数后重试。
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。

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

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