在 Bird 中存储一个邮件模板并按 id 引用它。条件判断、循环和默认值在消息发送时为每位收件人渲染，因此个性化逻辑留在模板中，而不是散落在你的代码各处。可用带声明变量的 HTML 进行创作，或渲染你的 React Email 组件。
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 Email API 的一部分。布局及其逻辑只存储一次；每次发送时引用模板并传入一组扁平的、每位收件人的值。Bird 在其一侧渲染最终消息，因此同一个模板既能驱动一封邮件，也能驱动百万封。
import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
// Store a template once. Conditionals and loops render per recipient at send.
const tpl = await bird.templates.create({
name: "order-confirmation",
subject: "Order {{ order_number }} confirmed",
html: "<h1>Thanks, {{ first_name or 'there' }}.</h1>" +
"{{ if is_member }}<p>You earned {{ points }} points.</p>{{ end }}",
variables: [
{ key: "first_name", type: "string", fallback: "there" },
{ key: "order_number", type: "string" },
{ key: "is_member", type: "boolean" },
{ key: "points", type: "number" },
],
});
// Send it. Bird fills in the blanks for each recipient.
await bird.email.send({
from: "orders@acme.com",
to: ["ada@example.com"],
template: tpl.id,
variables: { first_name: "Ada", order_number: "A-1043", is_member: true, points: 120 },
});不只是查找替换。
真正的模板逻辑，在 Bird 一侧、按收件人、在发送时解析。
- 01
条件判断。
仅当某个值适用时才显示某个区块，比如仅限会员的提示或免运费横幅，无需发送两个不同的模板。
- 02
循环。
为数组中的每一项重复一行，让一个订单确认模板列出客户实际购买的每一个商品行。
- 03
默认值。
当某个字段缺失时回退到一个安全值，让空白的名字永远不会变成空洞的问候语发出去。
- 04
嵌套数据。
用点分路径深入结构化对象，而不仅是扁平的顶层键，让你现有的数据结构直接映射进来。
- 05
丰富的变量类型。
声明的变量可以是字符串、数字、布尔值、数组和对象，这正是上面的循环和条件判断得以实现的基础。
用你既有的方式进行创作。
通过 API 发送带一组声明变量的纯 HTML，你就拥有了一个可用的模板，无需学习新的编辑器。更喜欢用组件？将你的 React Email 模板渲染为 HTML 并存储结果。唯一需要知道的一点：在 JSX 中将 Bird 的占位符保留为字面文本，使其在渲染后留存并在发送时填充，而不是在 React 渲染时就写死某个值。
import { render } from "@react-email/render";
import { Receipt } from "./emails/receipt";
// Author in React. Leave Bird's tokens as literal text so they
// survive the render and get personalized per recipient at send.
const html = await render(<Receipt firstName="{{ first_name }}" />);
await bird.templates.create({
name: "receipt",
subject: "Your receipt",
html,
variables: [{ key: "first_name", type: "string", fallback: "there" }],
});像你的其余代码一样带版本控制。
编辑在草稿上进行，绝不触及线上内容。发布会冻结一个不可变的、带编号的版本并推送它；如果某次改动出错，可回滚到更早的版本并重新发布。并发编辑会被捕获而非被悄悄覆盖，因此两个人同时处理同一个模板不会互相冲掉对方的修改。每个版本都带有稳定的身份标识，这正是按模板报告能正确归因打开和点击的原因。
让每个品牌保持一致。
品牌套件保存你的颜色、字体、间距、徽标和语调，并将它们应用到模板上，使输出在外观和文风上都像出自你之手，而无需逐个手动重新设计样式。套件存在于工作区层级，一个工作区可以保留多个，因为母品牌、子品牌和你普通的事务性邮件很少会想要相同的外观。使用套件是可选的：未配置套件的模板会回退到简洁的默认样式。
精确预览将要发出的内容。
用示例值填充模板，并在任何人收到之前查看渲染后的消息。预览走的是与真实发送相同的渲染路径，因此你批准的就是发出去的，而不是某个在占位符和逻辑对真实收件人解析后会出现偏差的近似版本。
模板的未来方向。
存储模板模型是后续功能的基础：用提示词描述一个模板并生成草稿以供润色、无需编写 HTML 即可可视化地构建模板、让编程智能体通过 MCP 编排符合品牌的模板，以及提供一个可作为起点的起始模板库。这些都建立在同一套带版本控制、品牌感知的模型之上，而非另起炉灶，因此你今天集成的 API 正是它们将要扩展的那一套。
在文档中深入了解。
了解模板如何契合发送指南，包括渲染 React Email，并接入邮件事件和 webhook，让打开和点击按模板回流。