Dùng mẫu thư trong Email API

Tạo mẫu thư có biến thay thế rồi gửi bằng template_id, để đổi nội dung thư mà không phải triển khai lại ứng dụng.

Nhúng HTML của thư vào mã nguồn nghĩa là mỗi lần sửa một dấu phẩy đều phải triển khai lại. Mẫu thư tách nội dung ra khỏi mã: ứng dụng chỉ gửi template_id và dữ liệu.

Chuẩn bị

Đã gửi được thư. Xem Gửi thư đầu tiên qua Email API

Xem danh sách mẫu

Vào Email API → Mẫu email.

Trang Mẫu Email: số mẫu đã dùng trên hạn mức ở đầu trang, nút Tạo mẫu email, ba bộ lọc Tất cả, Hệ thống và Của tôi, và danh sách mẫu hiện template_id, tiêu đề thư mặc định kèm biến, cùng các nút Xem đầy đủ, Nhân bản và Sửa

Ba bộ lọc chia mẫu làm hai nguồn:

Bộ lọc	Là gì
Hệ thống	mẫu Cloudfly dựng sẵn — dùng và nhân bản được, không sửa trực tiếp
Của tôi	mẫu bạn tạo — sửa và xoá được

Số mẫu tối đa theo gói hiện ngay đầu trang, dạng đã dùng / hạn mức.

Bắt đầu từ mẫu hệ thống

Cần thư đặt lại mật khẩu hay thư chào mừng thì đừng viết từ đầu. Mở bộ lọc Hệ thống, tìm mẫu gần nhất, bấm Nhân bản — bản sao thành mẫu của bạn và sửa được thoải mái.

Nhân bản cũng là cách sửa an toàn: mẫu gốc còn nguyên để đối chiếu nếu bản sửa hỏng.

`template_id` mới là thứ ứng dụng dùng

Mỗi mẫu có một template_id hiện ngay đầu thẻ, ví dụ welcome-email. Đó là giá trị bạn truyền trong lệnh gọi gửi thư, không phải tên hiển thị.

{
  "from": "no-reply@example.com",
  "to": "khach@example.net",
  "template_id": "welcome-email",
  "variables": { "name": "An", "company_name": "Công ty A" }
}

Danh sách tham số đầy đủ nằm ở Email API → Hướng dẫn trong bảng điều khiển.

Đổi template_id là làm hỏng ứng dụng đang chạy

template_id là hợp đồng giữa mẫu và mã nguồn của bạn. Đổi nó thì mọi lệnh gọi đang dùng giá trị cũ bị từ chối ngay, không có thời gian chuyển tiếp.

Cần đổi thật thì tạo mẫu mới với id mới, cập nhật ứng dụng, rồi mới xoá mẫu cũ.

Biến thay thế

Chỗ nào cần điền dữ liệu thì đặt biến trong mẫu, ví dụ {{name}}. Khi gửi, ứng dụng truyền giá trị tương ứng trong variables.

Biến dùng được cả trong tiêu đề lẫn trong thân thư — thẻ mẫu hiện Tiêu đề thư mặc định kèm biến để bạn thấy ngay.

Ba điều dễ vấp:

Thiếu biến khi gửi — chỗ đó ra trống hoặc lộ nguyên tên biến ra thư khách nhận. Truyền đủ mọi biến mẫu đang dùng.
Sai chính tả tên biến. {{fullName}} và {{fullname}} là hai biến khác nhau.
Nhét HTML vào biến. Biến để điền dữ liệu, không phải để ghép giao diện — cần đổi bố cục thì sửa mẫu.

Bấm Xem đầy đủ để soi toàn văn mẫu trước khi gửi thật.

Kiểm tra kết quả

Gửi một thư dùng template_id đó tới hộp thư của chính bạn
Lệnh gọi trả về mã chấp nhận
Thư tới nơi, và mọi biến đã được thay — không còn dấu ngoặc nhọn nào trong thư
Tiêu đề cũng đã thay biến, không riêng thân thư

Điểm 3 và 4 phải kiểm bằng mắt trên thư thật. Không lệnh gọi nào báo lỗi khi bạn quên một biến — nó gửi đi bình thường, chỉ có khách hàng thấy chỗ trống.