标签是附加在邮件上的 { name, value } 键值对。它们会随邮件一起存储，由 GET /emails/{id} 返回，并出现在该邮件的每个 Webhook 载荷中（以对象形式，"tags": { "category": "welcome" }）。你可以用它们把事件关联回自己的记录，而无需保存 SpacePost 的 id。

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: "<p>Hi</p>",
  tags: [
    { name: "category", value: "welcome" },
    { name: "user_id", value: "u_1042" },
  ],
});

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Welcome",
    "html": "<p>Hi</p>",
    "tags": [{ "name": "category", "value": "welcome" }, { "name": "user_id", "value": "u_1042" }]
  }'

X-SpacePost-Tags: category=welcome, user_id=u_1042

规则

每封邮件最多 50 个标签。
name 和 value 的长度均为 1 到 256 个字符，只能包含 ASCII 字母、数字、下划线和短横线（A-Z a-z 0-9 _ -）。
空格、点号、@ 和非 ASCII 字符会被以 422 拒绝。像邮箱地址这样的值，请先做哈希或转成 slug，例如 user_1042 或 SHA-256 十六进制摘要。