Template email
Template adalah baris subjek dan isi email yang Anda simpan sekali lalu kirim berkali-kali. Anda menulis bagian yang berubah sebagai placeholder {{ variable }}, memublikasikan template, lalu mengirimnya berdasarkan slug alih-alih menempelkan HTML yang sama ke setiap panggilan API. Sebuah template dimiliki oleh workspace Anda.
Buat dan kelola template di Email > Templates, melalui /v1/email/templates, dengan bird CLI, atau melalui MCP server. Metode bertipe tersedia di SDK TypeScript, Python, PHP, dan Go di bawah email.templates. Skema request dan response lengkap ada di referensi API. Kirim template yang sudah dipublikasikan melalui send endpoint biasa.
Isi sebuah template
Setiap template memiliki dua nama, dan keduanya berfungsi berbeda:
- slug adalah nama yang Anda gunakan untuk mengirim template, misalnya welcome-email. Anda memilihnya saat membuat template dan tidak dapat diubah setelahnya. Slug boleh berisi huruf kecil, angka, tanda hubung, dan garis bawah, harus diawali dan diakhiri dengan huruf atau angka, dan panjangnya maksimal 63 karakter. Dua prefiks tidak boleh digunakan: bird_, yang dicadangkan untuk template bawaan kami, dan emt_, yang merupakan format ID template. Dashboard menyebut kolom ini Alias.
- name adalah label tampilan berupa teks bebas. Nilai default-nya adalah slug, dan Anda bisa mengubahnya kapan saja. Tidak ada yang di-resolve melalui name, jadi mengganti nama template untuk tampilan tidak pernah mengganggu pengiriman.
Selain itu, template memiliki ID emt_ permanen yang tetap sepanjang masa pakainya. Template juga memiliki category, yaitu marketing atau transactional, dan source authoring: html, markup jadi yang Anda sediakan, opsional dipersonalisasi dengan Liquid. Category dan source keduanya ditetapkan saat Anda membuat template.
Kami menyediakan katalog template bawaan, dan slug-nya selalu diawali dengan bird_. Template bawaan tidak dimiliki oleh workspace mana pun, tidak bisa diedit, dan selalu siap dikirim apa adanya. Salin satu ke workspace Anda untuk menjadikannya milik Anda, dan template tersebut menjadi template biasa yang bisa Anda edit. Salinan tersebut hadir sebagai draf yang belum dipublikasikan dan mewarisi category, source, serta pengaturan bahasa dari template aslinya, jadi publikasikan terlebih dahulu sebelum mengirimnya.
Draf dan versi terpublikasi
Setiap template memiliki tepat satu draf, yaitu salinan kerja yang Anda edit. Template juga memiliki sejumlah versi terpublikasi, masing-masing bernomor (1, 2, 3, dan seterusnya) dan tidak pernah diubah lagi setelah ada. Pengeditan mengubah draf secara langsung. Publikasi mengambil snapshot dari draf saat ini, mengubahnya menjadi versi bernomor berikutnya, dan menjadikan versi tersebut yang digunakan pengiriman. Draf itu sendiri tetap bisa diedit, jadi Anda bisa terus mengerjakan versi berikutnya.
Aturan yang penting untuk pengiriman adalah ini: pengiriman selalu menggunakan versi terpublikasi dari template, dan draf tidak pernah dikirim sendiri. Anda bisa terus mengedit draf sementara versi stabil tetap terkirim, lalu memublikasikan saat perubahan sudah siap. Memublikasikan versi baru mengubah apa yang di-render oleh pengiriman selanjutnya. Pengiriman yang sudah diterima tidak terpengaruh oleh publikasi yang terjadi setelahnya.
Versi mendukung dua aksi tambahan. Buang perubahan draf untuk mereset draf kembali ke versi yang sedang dipublikasikan. Atau roll back untuk menjadikan versi terpublikasi sebelumnya sebagai versi yang digunakan pengiriman lagi. Anda hanya bisa roll back ke versi yang pernah dipublikasikan, tidak pernah ke draf itu sendiri. Roll back menggantikan draf dengan konten versi tersebut, sehingga apa pun yang belum disimpan di draf akan hilang, dan pengeditan selanjutnya dimulai dari versi yang Anda roll back. Roll back tidak membuat versi baru.
Untuk memilih gambar yang sudah ada, Anda memerlukan akses baca ke pustaka media ruang kerja. Untuk mengunggah, menempelkan, atau menyeret dan melepas gambar baru, Anda memerlukan akses tulis. Jika Sisipkan gambar dinonaktifkan atau Anda tidak dapat menelusuri pustaka atau mengunggah gambar, minta izin pustaka media yang sesuai kepada administrator ruang kerja. Izin mengedit template saja tidak memberikan akses ke pustaka media.
Di dasbor, pilih Visual > Sisipkan gambar untuk mencari di pustaka media atau mengunggah gambar PNG, JPEG, GIF, atau WebP hingga 5 MB. Gambar WebP statis dikonversi menjadi PNG atau JPEG. Pilih gambar untuk mengatur Deskripsi gambar, lebar tampilan, perataan, dan tautannya. Tandai sebagai Gambar dekoratif hanya jika gambar tidak menyampaikan informasi; gambar bertautan memerlukan deskripsi yang menjelaskan tujuannya. Setiap bahasa menyimpan deskripsi gambar dan tata letaknya sendiri.
Gunakan Ganti gambar untuk mengganti gambar yang dipilih sambil mempertahankan deskripsi, tautan, lebar, dan perataannya. Anda juga dapat menempelkan atau menyeret satu file gambar setiap kali ke editor visual. Tunggu hingga unggahan selesai, atau batalkan, sebelum menyimpan atau mengirim uji coba. Periksa pratinjau, lalu buka Tindakan lainnya > Email uji coba untuk mengirim konten saat ini kepada diri sendiri. Kode tetap tersedia untuk mengedit HTML.
Menghapus gambar dari pustaka media tidak menghapusnya dari email yang sudah dikirim. Penggantian gambar menggunakan URL baru, sehingga pesan sebelumnya tetap menampilkan gambar asli.
Penyimpanan dijaga oleh nomor revisi. Kirimkan revision yang terakhir Anda baca untuk bahasa yang sedang Anda simpan. Jika orang lain mengubah bahasa tersebut sementara itu, penyimpanan ditolak sebagai konflik alih-alih menimpa pekerjaan mereka. Hilangkan revision untuk menyimpan tanpa syarat. Publikasi dan roll back menggunakan revision milik draf dengan cara yang sama.
Konten dalam lebih dari satu bahasa
Template menyimpan konten dalam maksimal 25 bahasa, masing-masing dengan subjek dan isi sendiri, ditandai dengan kode BCP-47 seperti en atau pt-BR. Satu bahasa adalah default template. Memublikasikan template memublikasikan semua bahasa yang dimilikinya secara bersamaan. Anda tidak bisa memublikasikan satu bahasa saja, jadi semuanya harus diselesaikan terlebih dahulu. Setiap bahasa memerlukan subjek dan isi, dan bahasa default template harus salah satu dari bahasa yang sudah Anda isi. Jika ada yang kurang, tidak ada yang dipublikasikan, dan error memberi tahu apa yang kurang di setiap bahasa sehingga Anda bisa memperbaiki semuanya sekaligus. Anda tidak harus menyelesaikan semua bahasa di awal: publikasikan yang sudah siap, dan tambahkan sisanya nanti.
Sebuah bahasa memerlukan body HTML. Anda boleh mengosongkan text-nya: publikasi kemudian membuat alternatif plain-text dari HTML secara otomatis, sehingga Anda mendapat kedua bagian tanpa menulis yang kedua sendiri.
Setiap bahasa juga bisa membawa preview text, kadang disebut preheader: baris yang ditampilkan inbox setelah subjek di daftar pesannya. Ini opsional, maksimal 255 karakter, dan menerima placeholder {{ variable }} yang sama seperti subjek. Jika dikosongkan, inbox menampilkan baris pembuka body sebagai gantinya, yang jarang merupakan baris pilihan Anda. Publikasi menolak preview text pada bahasa yang body-nya tidak memiliki bagian HTML, karena klien email hanya membaca baris preview dari markup HTML tersembunyi, dan menolak {{ bird.unsubscribe_url }} di dalamnya untuk alasan yang sama subjek tidak bisa membawanya: keduanya bukan tempat link bisa disisipkan.
Dua pengaturan menangani pengiriman yang tidak menyebutkan bahasa yang dimiliki template, dan keduanya menjaga dari kesalahan yang berbeda:
| Pengaturan | Fungsinya |
|---|---|
| on_missing_language | Apa yang terjadi ketika pengiriman meminta bahasa yang tidak dimiliki template. fallback, nilai default, menyajikan kecocokan terdekat. Ia mencoba bentuk yang lebih luas dari bahasa yang sama terlebih dahulu, sehingga pt yang tersimpan bisa melayani permintaan untuk pt-BR. Kemudian ia kembali ke bahasa default template. fail menolak pengiriman tersebut, untuk konten yang mengirim bahasa yang salah lebih buruk daripada tidak mengirim sama sekali. |
| language_source_required | Apakah pengiriman harus menyebutkan bahasa. Pengaturan ini nonaktif secara default, sehingga pengiriman yang tidak menyebutkan bahasa mendapatkan bahasa default. Aktifkan, dan pengiriman tersebut ditolak. Broadcast menyebutkan satu bahasa untuk seluruh audiensnya, jadi template dengan pengaturan ini aktif memerlukan bahasa tersebut dipilih sebelum broadcast dapat dikirim. |
Anda bisa mengatur keduanya secara independen. fail sendiri hanya berlaku ketika pengiriman menyebutkan bahasa yang tidak kami miliki, sehingga pengiriman yang tidak menyebutkan bahasa tetap lolos. Aktifkan kedua pengaturan bersamaan jika Anda ingin setiap pengiriman menyebutkan bahasa secara eksplisit.
Personalisasi dengan variabel
Tulis placeholder {{ variable }} di subjek, preview text, dan body. Kami mendeteksinya secara otomatis, digabungkan dari semua bahasa, sehingga Anda tidak perlu mendeklarasikannya secara terpisah. Prefiks placeholder membedakan dua jenisnya. Path yang dimulai dengan bird. membaca dari data kami, baik catatan kontak maupun link berhenti berlangganan. Yang lainnya adalah parameter yang Anda berikan nilainya saat mengirim.
Nama parameter adalah satu kata, seperti {{ animal }}. Nama bertitik mengacu pada struktur yang tidak dimiliki parameter, sehingga memublikasikannya ditolak: tulis nilainya sebagai parameter tersendiri, atau baca data kontak dengan bird.contact.<attribute> sebagai gantinya.
Pada pengiriman tunggal atau batch, nilai parameter berasal dari objek template.parameters milik pengiriman, berdasarkan namanya. Satu set nilai mencakup semua penerima pengiriman tersebut. bird adalah satu nama yang tidak boleh Anda gunakan di situ: key template.parameters bernama bird ditolak dengan 422.
Broadcast tidak memiliki objek parameters, sehingga kontennya hanya bisa menggunakan placeholder bird.. bird.contact.<attribute> diisi dari properti kontak milik masing-masing penerima, yang menjadi cara personalisasi konten per penerima. Setiap properti kontak tersedia berdasarkan key-nya sendiri, begitu juga tiga field bawaan: first_name, last_name, dan email.
Contoh kode
Hi {{ bird.contact.first_name }},Setiap parameter dalam template memerlukan nilai saat Anda mengirim. Jika tidak, API mengembalikan 422 yang menyebutkan parameter yang kurang. Berikan nilai untuk parameter di semua bahasa karena bahasa yang dipilih bisa bergantung pada pengaturan fallback. Properti kontak yang kosong di-render sebagai nilai kosong, jadi tambahkan fallback untuk konten yang dilihat pelanggan: {{ bird.contact.first_name | default: "there" }}.
Broadcast lebih ketat soal nama yang diterima, karena contact property adalah satu-satunya sumber untuk mengisi placeholder. Placeholder bird.contact.*-nya hanya boleh menyebut built-in field atau contact property yang sudah didaftarkan di workspace. Placeholder lain, termasuk parameter, tidak bisa diisi oleh broadcast. Pengiriman ditolak, dan error menyebutkan nama placeholder yang bermasalah.
Yang berubah untuk template ketika Anda mengarsipkan sebuah property hanyalah konten baru: property tersebut hilang dari picker di editor, dan menerbitkan versi yang kontennya membaca property itu akan ditolak dengan menyebutkan nama property-nya. Versi yang diterbitkan sebelum pengarsipan tidak terpengaruh.
Placeholder menggunakan Liquid, jadi filter dan control flow bisa dipakai bersama substitusi biasa. Kondisional {% if %} dan loop {% for %} atas nilai array sama-sama valid. Beberapa konstruksi ditolak saat Anda menerbitkan, dan error menyebutkan persis apa yang perlu diubah:
- Partial include, menggunakan {% include %} atau {% render %}.
- Tag increment, decrement, dan ifchanged.
- Filter money, format_date, format_time, json, inspect, dan type.
- Perbandingan terhadap empty atau blank. Gunakan .size == 0 sebagai gantinya.
- Block bersarang jauh lebih dalam dari yang dibutuhkan markup email sesungguhnya.
Template broadcast tidak boleh menggunakan loop {% for %} sama sekali, karena broadcast mengisi satu nilai per contact property dan tidak punya apa-apa untuk diiterasi. Jika konten Anda membutuhkan loop, kirim melalui API messages sebagai gantinya.
Setiap template menggunakan Liquid, termasuk yang hanya berisi placeholder {{ variable }}. Sebelum diterbitkan, kami memvalidasi subject, preview text, HTML, dan konten plain-text sebagai Liquid. Kami juga menambahkan filter escape ke setiap output HTML yang belum diakhiri escape atau escape_once, agar nilai yang mengandung & atau < tidak bisa mengubah markup di sekitarnya. Output unsubscribe yang dicadangkan tetap tidak diubah agar pengiriman bisa menggantinya. Baris subject dan body plain-text dibiarkan apa adanya. Karena penerbitan menambahkan filter ini, HTML yang Anda baca dari versi yang diterbitkan mungkin tidak byte-identical dengan yang Anda kirimkan.
Masukkan URL lengkap langsung ke dalam href, misalnya <a href="{{ sign_in_url }}">Sign in</a>. Jangan tambahkan url_encode ke seluruh nilai. Filter ini meng-encode https://, /, ?, dan & dengan percent-encoding, sehingga hasilnya berhenti berfungsi sebagai link absolut. Kami menambahkan HTML escaping sambil mempertahankan struktur URL. Ketika sebuah parameter menyuplai satu komponen URL, encode komponen itu secara eksplisit: <a href="https://example.com/search?q={{ query | url_encode }}">Search</a>.
Pratinjau sebelum menerbitkan
Render template dengan nilai sampel dan dapatkan baris subject serta body HTML dan plain-text yang akan dikirimkan oleh sebuah send. Preview menggunakan renderer Liquid lokal kami dan secara default merender draft, sehingga Anda bisa memeriksa perubahan sebelum ditayangkan. Preview juga bisa merender versi yang sudah diterbitkan. Fitur ini berfungsi untuk template Anda sendiri maupun template bawaan kami, dan tidak ada yang dikirim.
Anda juga bisa menyerahkan kontennya sendiri alih-alih membiarkan preview membaca draft. Kirimkan subject dan body, dan keduanya akan dirender, diperlakukan persis seperti draft, sehingga editor bisa menampilkan perubahan saat diketik tanpa perlu menyimpan terlebih dahulu.
Personalisasi diisi untuk Anda, sehingga yang dikembalikan terbaca sebagai salinan jadi, bukan placeholder {{ }}. Sebutkan contact dan setiap bird.contact.<attribute> akan di-resolve berdasarkan properti kontak tersebut, sehingga Anda bisa memeriksa kata-kata Anda terhadap rekaman nyata sebelum siapa pun menerimanya. Nilai-nilai tersebut diambil dari proyeksi yang sama dengan yang digunakan broadcast untuk mengisi placeholder-nya, jadi preview menjawab dengan apa yang akan dijawab oleh send.
Kosongkan contact dan nilai pengganti akan disubstitusikan: Bird dan Test untuk nama depan dan belakang, bird.test@example.com untuk email, dan fallback terdaftar masing-masing property lainnya. Property yang direferensikan tapi tidak punya fallback dirender sebagai key-nya dalam kurung siku, seperti [loyalty_tier], yang memberi tahu Anda bahwa nilainya adalah placeholder sekaligus property mana yang masih memerlukan fallback.
Kontak dibaca sesuai kondisinya saat ini. Itu membuat preview cocok untuk memeriksa konten yang akan Anda kirim, dan tidak cocok untuk menanyakan apa yang dikirim oleh pengiriman sebelumnya. Untuk membaca apa yang benar-benar dikirimkan satu send, buka pesan tersebut di log email, yang merendernya dari nilai-nilai yang dibawa send itu.
Tambahkan language untuk merender satu bahasa tertentu, atau kosongkan untuk bahasa default template. Respons memberi tahu Anda bahasa mana yang dirender, yang penting ketika bahasa yang Anda minta tidak tersedia dan on_missing_language template menyajikan kecocokan terdekat.
Jika draft memiliki personalisasi yang akan ditolak saat Anda menerbitkan, preview mengembalikan error yang sama, jadi preview juga berfungsi sebagai cara menemukan masalah lebih awal.
Di template builder dashboard, Preview with contact data di bagian bawah panel kiri menampilkan email yang sudah dirender di samping apa pun yang sedang Anda edit, baik di editor visual maupun code editor. Picker di bawahnya memilih data siapa yang mengisi placeholder, dan Sample data adalah nilai pengganti di atas.
Mengirim dengan template
Atur field template pada send ke objek yang menyebutkan template, baik berdasarkan id (emt_...) maupun berdasarkan slug, gunakan tepat salah satu dari keduanya. Masukkan nilai variabelnya di template.parameters. Tambahkan language untuk memilih bahasa tertentu, atau kosongkan untuk mengirim bahasa default template, kecuali template mengharuskan setiap send menyebutkan bahasa. Kosongkan subject, html, dan text sepenuhnya, karena template sudah menyediakannya.
Contoh kode
{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"category": "transactional",
"template": {
"slug": "welcome-email",
"parameters": { "first_name": "Jane" }
}
}Satu perilaku yang perlu direncanakan: kategori template adalah nilai default, dan category milik send meng-override-nya. Kosongkan category, dan send mewarisi kategori template, sehingga template operasional dikirim sebagai transaksional tanpa Anda mengulanginya di setiap panggilan. Atur category, dan nilai Anda yang berlaku. Detail selengkapnya tentang kontrak sisi pengiriman ada di mengirim dengan template.
Authoring di luar dashboard
Seluruh lifecycle tersedia di luar dashboard. Langkah publish di sana dinamakan submit, dan itulah operasi yang mengubah draft menjadi versi terbitkan berikutnya:
Contoh kode
bird email templates create welcome-email --category marketing --source html
bird email templates versions languages set <emt_...> <emv_...> en --subject "Hi {{ bird.contact.first_name }}" --html "<p>Hello</p>"
bird email templates versions submit <emt_...> <emv_...> --validate-only # report problems, freeze nothing
bird email templates versions submit <emt_...> <emv_...> # freeze, go livecreate mengembalikan template beserta draft_version_id-nya, yang dibutuhkan setiap perintah version dan language. --validate-only menjalankan pemeriksaan kelengkapan yang sama seperti submit sungguhan, tanpa membekukan apa pun, jadi ini cara murah untuk menemukan semua masalah di seluruh bahasa dalam satu kali jalan. Membaca kembali template memberikan metadata dan status per bahasanya, tapi tanpa konten. Konten berada di language milik version, satu bahasa pada satu waktu.
SDK menyediakan lifecycle yang sama sebagai typed method di bawah email.templates, dengan operasi version dan language bersarang di bawahnya sebagai email.templates.versions dan email.templates.versions.languages. Agent mengakses operasi yang sama melalui tool email_templates_* MCP.
Langkah selanjutnya
- Mengirim email: payload send lengkap, dan bagaimana pengiriman bertemplat cocok dengannya
- Kategori: memilih marketing vs transactional di setiap pengiriman
- bird email templates: mengelola template dari terminal
- Referensi API: skema request dan response lengkap untuk semua delapan belas operasi template
- SDK: typed method email.templates di TypeScript, Python, PHP, dan Go
- Server MCP: memungkinkan agent membuat dan menerbitkan template
- Cara membuat template email: video yang membangun satu template di dashboard lalu meminta agent membangun satu lagi
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.