附件

在发送时，通过向 POST /v1/email/messages 载荷添加 attachments 数组来附加文件。每个条目在 content 中包含文件的 base64 编码字节，以及一个 filename。同样的数组也适用于批量发送中的条目。完整的请求和响应 schema 请参见 API 参考文档。

包含一个附件的发送

await bird.email.send({
  from: "hello@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your invoice",
  html: "<p>Thanks for your order. Your invoice is attached.</p>",
  attachments: [
    {
      filename: "invoice.pdf",
      content: "JVBERi0xLjcKJ...",
      content_type: "application/pdf",
    },
  ],
});

client.email.send(
    from_="hello@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Your invoice",
    html="<p>Thanks for your order. Your invoice is attached.</p>",
    attachments=[
        {
            "filename": "invoice.pdf",
            "content": "JVBERi0xLjcKJ...",
            "content_type": "application/pdf",
        }
    ],
)

_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:    "hello@yourdomain.com",
	To:      []string{"delivered@messagebird.dev"},
	Subject: "Your invoice",
	HTML:    "<p>Thanks for your order. Your invoice is attached.</p>",
	Attachments: []bird.EmailAttachment{{
		Filename:    "invoice.pdf",
		Content:     pdfBytes,
		ContentType: bird.String("application/pdf"),
	}},
})

$bird->email->send(
    from: 'hello@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Your invoice',
    html: '<p>Thanks for your order. Your invoice is attached.</p>',
    attachments: [
        (new EmailAttachment())
            ->setFilename('invoice.pdf')
            ->setContent('JVBERi0xLjcKJ...')
            ->setContentType('application/pdf'),
    ],
);

bird email send \
  --from hello@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject 'Your invoice' \
  --html '<p>Thanks for your order. Your invoice is attached.</p>' \
  --attach ./invoice.pdf

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your invoice",
    "html": "<p>Thanks for your order. Your invoice is attached.</p>",
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjcKJ...",
        "content_type": "application/pdf"
      }
    ]
  }'

CLI 会读取文件并为你进行 base64 编码；通过 API 你需要自行提供编码后的字节。Go SDK 接收原始字节并在传输时进行编码。

content 是原始文件字节的 base64 编码。content_type 是可选的：省略时，我们会根据 filename 扩展名推断 MIME 类型，无法识别的扩展名则回退为 application/octet-stream。发送的其他部分与发送邮件完全一致：202、异步模型、标签和元数据不受附件影响。

附件字段

字段	类型	必填	说明
`filename`	string	是	1 到 255 个字符；展示给收件人。不允许换行符或控制字符。
`content`	string	是	Base64 编码的文件字节。
`content_type`	string	否	MIME 类型；省略时根据文件名扩展名推断。
`content_id`	string	否	1 到 128 个字符，`[A-Za-z0-9._-]`。设置后文件将以内嵌方式而非附件方式呈现。

一封邮件最多可包含 20 个附件（attachments 上限为 20 个条目）。

内嵌图片

要将图片嵌入 HTML 正文而非作为附件，请为附件设置 content_id，并在标记中使用 cid: URL 引用它：

代码示例

{
  "html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
  "attachments": [
    {
      "filename": "banner.png",
      "content": "iVBORw0KGgoAAAANS...",
      "content_type": "image/png",
      "content_id": "welcome-banner"
    }
  ]
}

content_id 是 cid: 引用与附件之间的关联。每个内嵌图片在同一次发送中需要唯一的 content_id；重复的值会被拒绝并返回 422。没有 content_id 的附件将作为常规文件附件投递。

大小限制

如果发送的预估生成消息大小超过 20 MB，我们会返回 413 拒绝该发送。预估值为 HTML 正文加纯文本正文加所有附件在 base64 编码之后的大小。编码会将原始字节膨胀约 4/3 倍，因此一个 15 MB 的文件本身就已占满整个 20 MB 的预算。经验法则是，将原始附件内容的总大小控制在远低于 15 MB，以便正文和 MIME 封装仍有空间。

接收服务器可能施加更低的大小限制。Bird 接受的消息仍可能因收件方服务器拒绝其大小而被退回。请根据你发送目标的邮箱服务商和组织选择合适的附件大小。

关于接收消息，请参见入站消息大小。

可执行文件和脚本附件在验证时会被拒绝并返回 422，判断依据为 content_type 或文件名扩展名。被阻止的扩展名包括 .exe、.dll、.msi、.bat、.cmd、.scr、.jar、.js、.vbs、.ps1、.sh、.hta 和 .lnk。等效的 MIME 类型如 application/x-msdownload、application/java-archive 和 text/javascript 也会被阻止。此验证不是病毒扫描。要分发被阻止的文件，请将其托管在链接后面。

在批量发送中

批量发送中的每个条目都可以有自己的 attachments，字段约定和每条消息 20 MB 的限制相同。批量请求的序列化请求体还有自身的上限，base64 编码的附件会快速占用该空间；有关批量级别的限制及如何拆分，请参见批量发送。

读取和下载附件

API 读取操作不会返回附件字节。GET /v1/email/messages/{message_id} 返回一个仅包含元数据的 attachments 数组；每个条目包含附件的 id、filename、content_type、size（解码后字节数）和 inline：

代码示例

{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}

要获取原始字节，请调用 GET /v1/email/messages/{message_id}/attachments/{attachment_id}（参考文档）。它以文件自身的内容类型流式传输文件，并在 Content-Disposition 请求头中标明文件名。使用前需满足两个条件：

必须为工作区启用内容存储。存储关闭时不会保存任何内容可供下载。请参见 202 的含义。
附件在发送后保留 30 天。超过该期限后下载将返回 410 Gone。

404 表示该消息没有已存储的内容或没有该 ID 的附件；425 Too Early 表示附件仍在存储中，可以稍后重试请求。

后续步骤

发送邮件：发送载荷的其余部分，包括收件人、内容、标签和异步模型
批量发送：批量操作以及附件如何在多条消息中使用
API 参考文档：创建消息：完整的请求 schema，包括 attachments
API 参考文档：下载附件：检索端点及其状态码

继续查看此主题的文档、指南和示例。

动手实践并获取实施简报

相关资源