将主题和正文存储一次，发布为不可变版本，然后通过 slug 发送。Liquid 条件语句、循环和过滤器在消息生成时运行，因此个性化逻辑存在于模板中，而非分散在代码各处。可在仪表板构建器中编写，通过 bird CLI 编写，或让智能代理通过 MCP 完成。
import { BirdClient } from "@messagebird/sdk";
import { render } from "@react-email/render";
import { WelcomeEmail } from "./emails/welcome";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
const { data, error } = await bird.email.send({
from: "Bird <hello@bird.com>",
to: ["ada@example.com"],
subject: "Your invite is ready",
html: await render(<WelcomeEmail name="Ada" />),
}).safe();
if (error) throw error;
console.log(data.id);
// → "em_2bX91Yk8h..."
You can sign in any time at bird.com/login.
Your test API key is on your dashboard, ready to send.
存储一个模板。在发送时个性化。
标记语言已存储在 Bird 中。
模板是 Bird Email API 的一部分。只需存储一次布局及其逻辑；每次发送通过 slug 或 id 指定模板，并传入其令牌所需的值。最终消息在我们一侧渲染，因此同一模板可用于一封收据、一百封批量发送，或面向整个受众的广播。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
// No subject and no html: the template's published version supplies both.
const { data, error } = await bird.email
.send({
from: "orders@acme.com",
to: ["delivered@messagebird.dev"],
category: "transactional",
template: {
slug: "order-confirmation",
parameters: {
first_name: "Ada",
order: { number: "A-1043", total: "$42.00" },
},
},
})
.safe();
不只是查找替换。
Liquid，在消息生成时由 Bird 端解析。
- 01
条件判断。
Liquid if 块仅在其值适用时显示，例如会员专属提示或包邮横幅，一个模板即可涵盖两种情况。
- 02
循环。
for 循环为数组中的每个项目重复一行，因此一个订单确认模板可列出客户实际购买的每个商品。有一个限制需要提前了解：广播对每个联系人属性只携带单一值，没有可迭代的内容，因此包含循环的模板需通过消息 API 而非广播发送。
- 03
过滤器。
通过 Liquid 过滤器管道处理值后再渲染。default 过滤器可在缺少名字时捕获，避免发出空白称呼。
- 04
嵌套数据。
点号令牌可深入结构化对象，因此您可以传入完整的订单对象，直接在标记中引用其编号和总额，无需事先扁平化。
- 05
无需额外声明。
令牌列表从您的标记中读取，跨所有语言合并，因此无需维护与正文同步的单独变量模式。值可以是任何 JSON 类型：字符串、数字、布尔值、数组、对象。
用你既有的方式进行创作。
三种方式，通向同一模板。仪表板构建器是可视化方式。bird CLI 可通过脚本或部署步骤驱动整个生命周期，智能代理则通过 MCP 访问相同操作。已有 React Email 组件？将其渲染为 HTML 并存储结果，在 JSX 中将 Bird 的令牌保留为纯文本，使其在渲染后仍然存在，而非在 React 运行时被替换为固定值。
# Render React Email to HTML, then publish it as a template version.
node scripts/render-receipt.mjs > receipt.json
bird email templates create receipt --category transactional --source html
bird email templates versions languages set "$TEMPLATE" "$DRAFT" en \
--body-file receipt.json --yes
# --validate-only reports every problem across every language, freezing nothing.
bird email templates versions submit "$TEMPLATE" "$DRAFT" --validate-only --yes
bird email templates versions submit "$TEMPLATE" "$DRAFT" --yes
像你的其余代码一样带版本控制。
编辑在草稿上进行，不会影响线上内容，因为发送始终解析当前已发布版本，草稿永远不会被发送。发布会冻结一个不可变的编号版本并使其上线；如果更改出错，可回滚到早期版本。保存时会携带您最后读取的修订号，因此如果队友在此期间更改了该语言，保存将被拒绝为冲突，而非覆盖其工作。送达和互动统计按模板细分，让您看到哪个模板真正有效。
一个模板，最多支持 25 种语言。
一个模板可承载最多 25 种语言的内容，每种语言有独立的主题和正文，通过 BCP-47 标签（如 en 或 pt-BR）标识。发送时指定所需语言，或留空以使用模板默认语言。当发送请求的语言模板中没有时，on_missing_language 决定处理方式：fallback 提供最接近的匹配，因此对 pt-BR 的请求会由已有的 pt 响应；fail 则直接拒绝发送，适用于错误语言比不发送更糟的内容场景。
精确预览将要发出的内容。
用示例值填充模板，获取发送时将交付的主题、HTML 正文和纯文本正文。预览渲染草稿，用于在上线前检查更改；也可预览已发布版本，查看当前实际发出的内容。不会实际发送。预览还会运行与发布相同的个性化检查，因此会被拒绝的结构会在此处优先暴露。
模板的未来方向。
可视化构建器和包含四十个内置模板的入门库已随附提供，您可以将其中一个复制到工作区并从那里开始编辑。接下来的计划：通过提示词描述模板并获得可优化的草稿、更精简的代理编写界面，以及品牌套件——在工作区级别保存您的颜色、字体和语调，并据此为模板设置样式。每项功能都扩展自同一版本化模型，因此您今天集成的内容正是它们的构建基础。
在文档中深入了解。
模板指南涵盖草稿、已发布版本、多语言内容和 Liquid 规则。发送指南包含发送端约定，邮件事件和 Webhooks 帮助您获取打开和点击的回传数据。