Cơ sở kiến thức

Mẫu thư

Một nội dung thư viết một lần, có phiên bản, và gửi đi nhiều lần: từ trình soạn thư, từ mã của chính bạn, hoặc bởi một agent.

Chi tiết

Một mẫu thư thuộc về kết nối chứ không thuộc về người đã viết ra nó, và đó chính là lý do bản đầu tiên của tính năng này bị thay thế. Bản đó khoá theo người dùng: mẫu thư của một đồng nghiệp là vô hình với một API key cấp workspace, nên một tích hợp không thể gửi thứ mà người thiết lập nó nhìn thấy, và xoá tài khoản của tác giả sẽ kéo theo toàn bộ mẫu thư của workspace. Các bản ghi đã được chuyển sang chứ không bị bỏ đi.
Có hai cách soạn nội dung thư. Một cây khối dựng trên các thành phần của @react-email/components (Section, Row, Column, Container, Text, Heading, Button, Link, Img, Hr, Markdown, CodeBlock, CodeInline), được kiểm tra ngay khi viết, nên một node hỏng hoặc một href không an toàn sẽ bị từ chối ngay tại lời gọi ghi nó thay vì đến nơi dưới dạng một email vỡ. Hoặc markup do chính bạn kết xuất: nếu các mẫu thư của bạn vốn đã là component react-email trong repo của bạn, hãy kết xuất chúng ở đó bằng @react-email/render rồi gửi HTML lên, phần HTML đó được làm sạch một lần khi phiên bản được xuất bản.
Hai mươi ba điểm khởi đầu cộng một mẫu trắng, bày trong một thư viện hình ảnh chứ không phải một menu, bởi đây là những thứ bạn phải nhìn tận mắt trước khi chọn giữa chúng, nên mỗi thẻ đều hiển thị chính email đó. Chào mừng và xác minh, biên nhận và hoá đơn, vận chuyển và gia hạn, bản tin tổng hợp và thông báo, sắp xếp dưới bốn đề mục, và mỗi mẫu đều mở ra trong trình soạn trực quan với mọi mảnh đều di chuyển, đổi kiểu và xoá được. Dù bạn chọn mẫu nào thì nó cũng đến dưới dạng bản nháp, nên chưa gửi được gì cho tới khi bạn xuất bản.
Thư viện mẫu là phần duy nhất ở đây chỉ có trong ứng dụng. Một lời gọi đến mẫu thư từ mã của bạn hoặc từ một agent sẽ gửi lên một nội dung thư (một tài liệu khối hoặc markup của riêng bạn) chứ không nêu tên một điểm khởi đầu, nên hai mươi ba mẫu kia là chỗ để bắt đầu chứ không phải một danh mục để cài đặt từ đó.
Slot có tên và prop có tên là hai loại chỗ trống, viết dưới dạng {{key}} trong nội dung thư và trong tiêu đề. Slot do người chỉnh sửa mẫu thư điền và mang theo một giá trị mặc định, nên một lần gửi không nêu gì vẫn kết xuất được. Prop được cung cấp lúc gửi, và một prop đánh dấu required sẽ khiến lần gửi bị từ chối khi nó vắng mặt: một 422, và không thư nào rời đi. Chính sự từ chối đó là lý do để khai báo nó: phương án còn lại là một thư đi ra với khoảng trống ở chỗ đáng lẽ là mã đơn hàng, điều mà không gì báo cáo và không ai thu hồi được.
Một phiên bản đã xuất bản là bất biến. Sửa nội dung của một mẫu thư đã xuất bản sẽ tạo ra một bản nháp mới chứ không viết đè lên bản đang chạy, nên các lần gửi vẫn phân giải đúng thứ chúng đã phân giải hôm qua cho tới khi có người xuất bản, và một lần gửi ghim theo số phiên bản thì kể cả khi đó cũng không bị ảnh hưởng. Nội dung thư được biên dịch lúc xuất bản, chính điều đó khiến một mẫu thư không kết xuất được sẽ hỏng với người xuất bản nó chứ không phải với người nhận.
Xem trước kết xuất đúng thứ mà một lần gửi sẽ tạo ra mà không gửi đi, và nó báo lại những chỗ còn trống thay vì từ chối. Một mẫu thư đang được xem trước thường là một mẫu thư đang được viết, và một tác giả điền từng khối một thì không nên bị buộc phải thoả mãn mọi prop mới thấy được những gì mình đã làm.
Mỗi mẫu thư mang theo hồ sơ riêng về những gì nó đã gửi: bao nhiêu thư đã đi trong bảy, ba mươi hoặc chín mươi ngày qua, thư nào được mở và thư nào được nhấp, một chuỗi số liệu theo từng ngày, và một bảng tách theo nơi mỗi lần gửi xuất phát: trình soạn thư, mã của bạn, một agent, hay hàng đợi. Mỗi tỷ lệ nêu rõ mẫu số của chính nó chứ không mượn của nhau, vì chúng thực sự khác nhau: lượt mở được tính trên những thư có mang pixel, lượt nhấp tính trên những thư có mang liên kết đã viết lại, và một thư có thể mang cái này mà không mang cái kia. Một lần xem trước thì không bao giờ được ghi lại, còn một lần gửi thử được đếm riêng và loại khỏi mọi con số, vì nó chưa từng rời đi.
Hồ sơ đó thành thật về những gì nó không nhìn thấy, và đó là lý do để tin vào nửa mà nó nhìn thấy. Một lần gửi được khớp với bản ghi phân phát của nó nhờ chính lần gửi ấy, và chỉ thư gửi từ mã của bạn hoặc từ hàng đợi mới mang theo bản ghi đó. Thư gửi từ trình soạn thư, từ một agent hay do trợ lý gửi thì không. Vì vậy một mẫu thư dùng chủ yếu từ trình soạn thư sẽ đến với phần lớn lần gửi không khớp được, và số lượng không khớp được hiển thị thành con số riêng chứ không gộp vào như thể không ai mở thư.
Bốn bề mặt trên cùng một dịch vụ, nên câu hỏi “xuất bản nghĩa là gì” có một câu trả lời duy nhất thay vì ba câu hôm nay còn trùng khớp. Nút Templates trong trình soạn thư đưa ra các mẫu đã xuất bản và THAY THẾ thư bằng mẫu bạn chọn chứ không dán nó vào: lần gửi nêu tên mẫu thư, phiên bản được ghim ngay tại thời điểm bạn chọn, và nội dung được kết xuất tại nơi nó được soạn, nên một lần xuất bản xen giữa lúc chọn và lúc bấm cũng không thể đổi thứ đi ra, và một bố cục mà trình soạn thư không thể giữ nổi vẫn còn nguyên vẹn. Thứ bạn điền ở đó là các giá trị, không phải nội dung thư. /templates là chín endpoint nằm sau scope templates:read và templates:write, được SDK bọc lại theo từng phương thức. Gửi một mẫu cần quyền gửi bên cạnh quyền với mẫu thư, nên một key cấp cho một công cụ viết nội dung có thể soạn và xuất bản mà không gửi được thư cho ai. Máy chủ MCP mang năm công cụ: list, read, preview, create và send. Cố ý không có công cụ nào để cập nhật, xoá hay xuất bản một mẫu đã có. Một lần sửa tạo ra bản nháp mà lần gửi kế tiếp sẽ không phân giải tới, còn một lần xoá thì không lấy lại được. Sửa một nội dung đã lưu là việc của màn hình: /workspace/templates có một khung dựng khối kèm bảng thành phần và một khung thuộc tính, một bản xem trước trực tiếp bên cạnh, cùng Save và Publish là hai hành động tách rời, chính điều đó khiến một phiên bản đã xuất bản là thứ bạn có thể để yên trong lúc làm bản kế tiếp.
200 mẫu thư trên mỗi kết nối, một tài liệu khối tối đa 500 khối, tám cấp lồng nhau, 20.000 ký tự trong bất kỳ giá trị nào, 100 slot và 100 prop; nội dung gửi lên dưới dạng markup tối đa một triệu ký tự, và tiêu đề tối đa 998. Mỗi con số đó là một hàng rào chắn một script chạy loạn chứ không phải giới hạn theo gói, mỗi lần từ chối đều kèm thông báo nêu rõ con số đã bị vượt, và không phần nào của mẫu thư nằm sau một hạng gói.