附件

attachments 是最多包含 50 个对象的数组。每个附件都需要 filename，并且 content 和 path 中恰好有一个。

filenamestring必填

1 到 255 个字符。会显示给收件人。

contentstring可选

以 base64 编码的文件字节。SDK 也接受 Buffer/Uint8Array，并会为你编码。与 path 二选一。

pathstring可选

公开的 https URL。SpacePost 会在发送邮件时下载它。与 content 二选一。

content_typestring可选

MIME 类型，例如 application/pdf。SDK 中的别名为 contentType。

content_idstring可选

将附件设为内联，可在 HTML 中以 cid:<content_id> 引用。SDK 中的别名为 contentId。

限制

整封邮件（包含 base64 编码后的所有附件）必须小于 40 MB。Base64 会使文件体积增加约 33%，因此原始文件总大小请控制在约 30 MB 以内。
URL 附件（path）必须使用 https，必须解析到公网地址（私有网络会被拒绝），抓取超时为 10 秒，且不能发生重定向。抓取失败会将邮件标记为 failed。
邮件发送后，附件内容会从存储中删除；日志中仅保留元数据（名称、类型、大小）。

通过内容添加附件

import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <billing@acme.com>",
  to: "user@example.com",
  subject: "Invoice 1042",
  text: "Your invoice is attached.",
  attachments: [{ filename: "invoice-1042.pdf", content: await readFile("invoice-1042.pdf"), contentType: "application/pdf" }],
});

console.log(error ?? data);

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme <billing@acme.com>\",
    \"to\": [\"user@example.com\"],
    \"subject\": \"Invoice 1042\",
    \"text\": \"Your invoice is attached.\",
    \"attachments\": [{
      \"filename\": \"invoice-1042.pdf\",
      \"content_type\": \"application/pdf\",
      \"content\": \"$(base64 -w0 invoice-1042.pdf)\"
    }]
  }"

在 macOS 上请使用 base64 -i invoice-1042.pdf（不带 -w0）。

import base64

with open("invoice-1042.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

requests.post(
    "https://api.spacepost.dev/emails",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json={
        "from": "Acme <billing@acme.com>",
        "to": ["user@example.com"],
        "subject": "Invoice 1042",
        "text": "Your invoice is attached.",
        "attachments": [{"filename": "invoice-1042.pdf", "content_type": "application/pdf", "content": content}],
    },
)

通过 URL 添加附件

{
  "from": "Acme <billing@acme.com>",
  "to": ["user@example.com"],
  "subject": "Your report",
  "text": "Report attached.",
  "attachments": [{ "filename": "report.pdf", "path": "https://files.acme.com/reports/2026-10.pdf" }]
}

内联图片

设置 content_id，并在 HTML 中用 cid: URL 引用它。

import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: '<img src="cid:logo" alt="Acme" width="120" /><p>Welcome aboard.</p>',
  attachments: [{ filename: "logo.png", content: await readFile("logo.png"), contentType: "image/png", contentId: "logo" }],
});

内联图片会作为邮件的一部分发送，显示时无需网络请求，但许多客户端（尤其是网页版 Gmail）在图片较小时显示效果最好。对于较大的图片，请托管在你自己的 CDN 上，并使用普通的 https:// URL。