Szablony e-mail

Szablon to temat i treść e-maila, które zapisujesz raz i wysyłasz wielokrotnie. Części, które się zmieniają, zapisujesz jako placeholdery {{ variable }}, publikujesz szablon, a potem wysyłasz go po slugu zamiast wklejać ten sam HTML w każde wywołanie API. Szablon należy do Twojego obszaru roboczego.

Twórz szablony i zarządzaj nimi w Email > Templates, przez /v1/email/templates, za pomocą bird CLI lub przez serwer MCP. Typowane metody są dostępne w SDK TypeScript, Python, PHP i Go w email.templates. Pełne schematy żądań i odpowiedzi znajdziesz w dokumentacji API. Opublikowany szablon wysyłaj przez standardowy endpoint wysyłki.

Co zawiera szablon

Każdy szablon ma dwie nazwy i każda pełni inną rolę:

slug to nazwa, po której wysyłasz szablon, na przykład welcome-email. Wybierasz ją przy tworzeniu szablonu i nie można jej potem zmienić. Slug może zawierać małe litery, cyfry, myślniki i podkreślenia, musi zaczynać się i kończyć literą lub cyfrą i może mieć maksymalnie 63 znaki. Dwa prefiksy są zarezerwowane: bird_, używany przez nasze wbudowane szablony, oraz emt_, będący formatem identyfikatorów szablonów. W dashboardzie to pole nazywa się Alias.
name to dowolna etykieta wyświetlana. Domyślnie przyjmuje wartość slugu i możesz ją zmienić w każdej chwili. Nic nie jest rozwiązywane przez nazwę, więc zmiana nazwy szablonu na potrzeby wyświetlania nigdy nie psuje wysyłki.

Oprócz nich szablon ma stały identyfikator emt_, który nie zmienia się przez cały czas jego istnienia. Ma też category, czyli marketing lub transactional, oraz source określający sposób tworzenia: html, gotowy markup, który dostarczasz, opcjonalnie spersonalizowany za pomocą Liquid. Kategoria i źródło są ustalane na stałe przy tworzeniu szablonu.

Udostępniamy katalog wbudowanych szablonów, których slugi zaczynają się od bird_. Wbudowany szablon nie należy do żadnego obszaru roboczego, nie można go edytować i zawsze jest gotowy do wysłania w obecnej postaci. Skopiuj go do swojego obszaru roboczego, a stanie się zwykłym szablonem, który możesz edytować. Kopia pojawia się jako nieopublikowany szkic dziedziczący kategorię, źródło i ustawienia językowe oryginału, więc opublikuj ją przed wysłaniem.

Szkice i opublikowane wersje

Każdy szablon ma dokładnie jeden szkic, czyli kopię roboczą, którą edytujesz. Ma też dowolną liczbę opublikowanych wersji, z których każda jest numerowana (1, 2, 3 itd.) i po utworzeniu nigdy nie jest zmieniana. Edycja zmienia szkic w miejscu. Publikacja tworzy migawkę bieżącego szkicu, zamienia ją w kolejną numerowaną wersję i ustawia tę wersję jako używaną przez wysyłki. Sam szkic pozostaje edytowalny, więc możesz od razu pracować nad następną wersją.

Reguła istotna przy wysyłaniu jest taka: wysyłka zawsze używa opublikowanej wersji szablonu, a szkic nigdy nie jest wysyłany samodzielnie. Możesz edytować szkic, podczas gdy stabilna wersja jest nadal wysyłana, i opublikować, gdy zmiana jest gotowa. Opublikowanie nowej wersji zmienia to, co renderują późniejsze wysyłki. Na wysyłkę, która została już zaakceptowana, późniejsza publikacja nie ma wpływu.

Karta Versions szablonu z wierszem Draft oraz opublikowanymi wierszami v3, v2 i v1 z datami utworzenia i publikacji

Wersje obsługują jeszcze dwie akcje. Odrzuć zmiany szkicu, aby zresetować szkic do aktualnie opublikowanej wersji. Albo przywróć wcześniejszą wersję, aby ponownie ustawić starszą opublikowaną wersję jako tę używaną przez wysyłki. Przywrócić można tylko wersję, która została opublikowana, nigdy sam szkic. Przywrócenie zastępuje szkic zawartością tej wersji, więc wszystko niezapisane w szkicu przepada, a dalsze edytowanie zaczyna się od przywróconej wersji. Przywrócenie nie tworzy nowej wersji.

Aby wybrać istniejący obraz, potrzebujesz uprawnienia do odczytu biblioteki multimediów obszaru roboczego. Aby przesłać, wkleić lub przeciągnąć i upuścić nowy obraz, potrzebujesz uprawnienia do zapisu. Jeśli opcja Wstaw obraz jest wyłączona lub nie możesz przeglądać biblioteki albo przesyłać obrazów, poproś administratora obszaru roboczego o odpowiednie uprawnienie do biblioteki multimediów. Samo uprawnienie do edycji szablonów nie daje dostępu do biblioteki multimediów.

W panelu wybierz Wizualny > Wstaw obraz, aby przeszukać bibliotekę multimediów lub przesłać obraz PNG, JPEG, GIF albo WebP o rozmiarze do 5 MB. Statyczne obrazy WebP są konwertowane na PNG lub JPEG. Wybierz obraz, aby ustawić jego Opis obrazu, szerokość wyświetlania, wyrównanie i link. Oznacz go jako Obraz dekoracyjny tylko wtedy, gdy nie przekazuje informacji. Obraz z linkiem wymaga opisu wyjaśniającego, dokąd prowadzi link. Każdy język zachowuje własne opisy obrazów i układ.

Użyj opcji Zastąp obraz, aby zmienić wybrany obraz, zachowując jego opis, link, szerokość i wyrównanie. Możesz też wklejać lub przeciągać pliki obrazów do edytora wizualnego, po jednym naraz. Przed zapisaniem lub wysłaniem testu poczekaj na zakończenie przesyłania albo je anuluj. Sprawdź podgląd, a następnie otwórz Więcej działań > E-mail testowy, aby wysłać sobie bieżącą treść. Tryb Kod nadal umożliwia edycję HTML.

Usunięcie obrazu z biblioteki multimediów nie usuwa go z już wysłanych e-maili. Zastąpienie obrazu powoduje użycie nowego adresu URL, więc wcześniejsze wiadomości nadal wyświetlają oryginał.

Zapisywanie jest chronione numerem rewizji. Wyślij revision, który ostatnio odczytałeś dla zapisywanego języka. Jeśli ktoś inny zmienił ten język w międzyczasie, zapis zostaje odrzucony jako konflikt zamiast nadpisywania cudzej pracy. Pomiń revision, aby zapisać bezwarunkowo. Publikacja i przywracanie używają revision szkicu w ten sam sposób.

Zawartość w wielu językach

Szablon przechowuje zawartość w maksymalnie 25 językach, każdy z własnym tematem i treścią, oznaczony kodem BCP-47, takim jak en lub pt-BR. Jeden język jest domyślnym językiem szablonu. Publikacja szablonu publikuje jednocześnie wszystkie języki, które zawiera. Nie można opublikować jednego języka osobno, więc wszystkie muszą być wcześniej ukończone. Każdy język wymaga tematu i treści, a domyślny język szablonu musi być jednym z języków, które wypełniłeś. Jeśli czegoś brakuje, nic nie zostaje opublikowane, a błąd informuje, czego brakuje w każdym języku, abyś mógł naprawić wszystko za jednym razem. Nie musisz kończyć wszystkich języków od razu: opublikuj te, które są gotowe, a resztę dodaj później.

Język wymaga treści HTML. Możesz pominąć jego text: publikacja automatycznie utworzy alternatywę w postaci zwykłego tekstu na podstawie HTML, więc otrzymujesz obie części bez ręcznego pisania drugiej.

Każdy język może też zawierać tekst podglądu, nazywany czasem preheaderem: wiersz, który skrzynka odbiorcza wyświetla po temacie na liście wiadomości. Jest opcjonalny, ma maksymalnie 255 znaków i przyjmuje te same placeholdery {{ variable }} co temat. Jeśli go pominiesz, skrzynka odbiorcza użyje pierwszego wiersza treści, co rzadko jest wierszem, który byś wybrał. Publikacja odrzuca tekst podglądu dla języka, którego treść nie ma części HTML, ponieważ klient poczty odczytuje wiersz podglądu wyłącznie z ukrytego markupu HTML, oraz odrzuca {{ bird.unsubscribe_url }} wewnątrz niego z tego samego powodu, dla którego temat nie może go zawierać: żadne z tych miejsc nie nadaje się na link.

Dwa ustawienia dotyczą wysyłki, która nie podaje języka, dla którego szablon ma zawartość, i chronią przed różnymi błędami:

Ustawienie	Co kontroluje
on_missing_language	Co się dzieje, gdy wysyłka żąda języka, którego szablon nie ma. fallback, wartość domyślna, serwuje najbliższe dopasowanie. Najpierw próbuje szerszej formy tego samego języka, więc zapisany pt może obsłużyć żądanie pt-BR. Następnie cofa się do domyślnego języka szablonu. fail odrzuca wysyłkę, gdy wysłanie w złym języku jest gorsze niż niewysłanie w ogóle.
language_source_required	Czy wysyłka musi wskazać język. Domyślnie wyłączone, więc wysyłka bez wskazanego języka otrzymuje język domyślny. Po włączeniu taka wysyłka jest odrzucana. Broadcast wskazuje jeden język dla całej grupy odbiorców, więc szablon z tym ustawieniem wymaga wybrania języka, zanim broadcast będzie mógł wysłać.

Możesz ustawić te dwa parametry niezależnie. Sam fail działa tylko wtedy, gdy wysyłka podaje język, którego nie mamy, więc wysyłka bez podanego języka nadal przechodzi. Włącz oba ustawienia razem, gdy chcesz, aby każda wysyłka celowo podawała język.

Personalizacja za pomocą zmiennych

Zapisuj placeholdery {{ variable }} w temacie, tekście podglądu i treści. Zbieramy je automatycznie ze wszystkich języków, więc nie musisz ich deklarować osobno. Prefiks placeholdera rozróżnia dwa rodzaje. Ścieżka zaczynająca się od bird. czyta z naszych danych, czyli z rekordu kontaktu lub linku rezygnacji z subskrypcji. Wszystko inne jest parametrem, któremu nadajesz wartość przy wysyłce.

Nazwa parametru to pojedyncze słowo, na przykład {{ animal }}. Nazwa z kropką próbuje sięgnąć do struktury, której parametr nie posiada, dlatego publikacja takiego parametru jest odrzucana: zapisz wartość jako osobny parametr albo czytaj dane kontaktu za pomocą bird.contact.<attribute>.

W pojedynczej wysyłce lub wysyłce zbiorczej wartość parametru pochodzi z obiektu template.parameters wysyłki, indeksowanego po nazwie. Jeden zestaw wartości obejmuje wszystkich odbiorców danej wysyłki. bird to jedyna nazwa, której nie możesz tam użyć: klucz template.parameters o nazwie bird jest odrzucany z błędem 422.

Broadcast nie ma obiektu parameters, więc jego zawartość może używać wyłącznie placeholderów bird.. bird.contact.<attribute> jest wypełniany na podstawie właściwości kontaktu każdego odbiorcy, co personalizuje treść dla poszczególnych odbiorców. Każda właściwość kontaktu jest dostępna po swoim kluczu, a także trzy wbudowane pola: first_name, last_name i email.

Przykład kodu

Hi {{ bird.contact.first_name }},

Każdy parametr w szablonie musi mieć wartość w momencie wysyłki. W przeciwnym razie API zwraca 422 z nazwą brakującego parametru. Podawaj wartości parametrów dla wszystkich języków, ponieważ wybrany język może zależeć od ustawień awaryjnych. Brakująca właściwość kontaktu renderuje się jako pusta wartość, więc dodaj fallback dla treści widocznych przez klienta: {{ bird.contact.first_name | default: "there" }}.

Broadcast jest bardziej restrykcyjny co do akceptowanych nazw, ponieważ jedyne źródło wartości dla placeholderów stanowią właściwości kontaktu. Jego placeholdery bird.contact.* mogą wskazywać wyłącznie pole wbudowane albo właściwość kontaktu zarejestrowaną w obszarze roboczym. Każdy inny placeholder, w tym parametr, to wartość, której broadcast nie ma skąd pobrać. Wysyłka jest odrzucana, a błąd wskazuje nazwę placeholdera.

Archiwizacja właściwości wpływa na szablon tylko w zakresie nowej treści: właściwość znika z selektora w edytorze, a publikacja wersji, której treść z niej korzysta, jest odrzucana ze wskazaniem nazwy właściwości. Wersje opublikowane przed archiwizacją pozostają bez zmian.

Placeholdery używają Liquid, więc filtry i sterowanie przepływem działają obok zwykłego podstawiania. Warunek {% if %} i pętla {% for %} po wartości tablicowej są dozwolone. Kilka konstrukcji jest odrzucanych przy publikacji, a błąd wskazuje dokładnie, co zmienić:

Częściowe dołączenia (partial includes) za pomocą {% include %} lub {% render %}.
Tagi increment, decrement i ifchanged.
Filtry money, format_date, format_time, json, inspect i type.
Porównywanie z empty lub blank. Użyj .size == 0 zamiast tego.
Bloki zagnieżdżone znacznie głębiej, niż wymaga tego rzeczywisty markup e-maila.

Szablon broadcastu nie może w ogóle używać pętli {% for %}, ponieważ broadcast wypełnia jedną wartość na właściwość kontaktu i nie ma po czym iterować. Jeśli Twoja treść wymaga pętli, wyślij ją przez API wiadomości.

Każdy szablon używa Liquid, nawet taki, który zawiera wyłącznie placeholdery {{ variable }}. Przed publikacją walidujemy temat, tekst podglądu, HTML i treść tekstową jako Liquid. Do każdego wyjścia HTML, które nie kończy się już na escape lub escape_once, dodajemy również filtr escape, dzięki czemu wartość zawierająca & lub < nie może zmienić otaczającego markupu. Zarezerwowane wyjście z linkiem rezygnacji z subskrypcji pozostaje niezmienione, aby wysyłka mogła je zastąpić. Temat i treść tekstowa pozostają bez zmian. Ponieważ publikacja dodaje te filtry, HTML odczytany z opublikowanej wersji może nie być bajt po bajcie identyczny z tym, co przesłano.

Umieść kompletny URL bezpośrednio w href, na przykład <a href="{{ sign_in_url }}">Sign in</a>. Nie dodawaj url_encode do całej wartości. Koduje on procentowo https://, /, ? i &, co uniemożliwia działanie wyniku jako linku bezwzględnego. Dodajemy eskejpowanie HTML, zachowując strukturę URL. Gdy parametr dostarcza pojedynczy komponent URL, zakoduj go jawnie: <a href="https://example.com/search?q={{ query | url_encode }}">Search</a>.

Podgląd przed publikacją

Wyrenderuj szablon z przykładowymi wartościami i otrzymaj temat oraz treść HTML i tekstową, które wysyłka by dostarczyła. Podgląd korzysta z naszego lokalnego renderera Liquid i domyślnie renderuje wersję roboczą, co pozwala sprawdzić zmianę, zanim wejdzie na produkcję. Może też wyrenderować opublikowaną wersję. Działa zarówno z Twoimi szablonami, jak i z wbudowanymi, i nic nie jest wysyłane.

Możesz też sam przekazać treść zamiast czytać ją z wersji roboczej. Podaj temat i treści, a zostaną wyrenderowane dokładnie tak, jak wersja robocza. To pozwala edytorowi wyświetlać zmianę w trakcie pisania, bez wcześniejszego zapisywania.

Personalizacja jest uzupełniana automatycznie, więc wynik wygląda jak gotowa treść zamiast placeholderów {{ }}. Wskaż contact, a każdy bird.contact.<attribute> zostanie rozwiązany na podstawie właściwości tego kontaktu. W ten sposób sprawdzasz brzmienie tekstu na prawdziwym rekordzie, zanim ktokolwiek go otrzyma. Wartości pochodzą z tej samej projekcji, której broadcast używa do wypełniania placeholderów, więc podgląd odpowiada tym, czym odpowiedziałaby wysyłka.

Pomiń contact, a zamiast tego zostaną podstawione wartości zastępcze: Bird i Test jako imię i nazwisko, bird.test@example.com jako adres e-mail oraz zarejestrowana wartość domyślna każdej innej właściwości. Właściwość bez wartości domyślnej renderuje się jako jej klucz w nawiasach kwadratowych, na przykład [loyalty_tier]. To informuje zarówno o tym, że wartość jest placeholderem, jak i o tym, która właściwość wciąż wymaga wartości domyślnej.

Kontakt jest odczytywany w bieżącym stanie. To czyni podgląd właściwym narzędziem do sprawdzania treści, którą zamierzasz wysłać, ale niewłaściwym do sprawdzania, co zawierała wcześniejsza wysyłka. Aby zobaczyć, co faktycznie dostarczyła konkretna wysyłka, otwórz tę wiadomość w logu e-mail. Log renderuje ją na podstawie wartości, które niosła ta wysyłka.

Dodaj language, aby wyrenderować konkretny język, lub pomiń go, aby użyć domyślnego języka szablonu. Odpowiedź informuje, który język został wyrenderowany. Ma to znaczenie, gdy żądany język nie jest dostępny, a on_missing_language szablonu zwróciło najbliższe dopasowanie.

Jeśli wersja robocza zawiera personalizację, która zostałaby odrzucona przy publikacji, podgląd zwraca ten sam błąd. Służy więc też jako sposób na wczesne wykrywanie problemów.

W kreatorze szablonów w dashboardzie opcja Preview with contact data na dole lewego panelu wyświetla wyrenderowany e-mail obok edytowanej treści, zarówno w edytorze wizualnym, jak i kodowym. Selektor poniżej pozwala wybrać, czyje dane wypełnią placeholdery, a Sample data to opisane wyżej wartości zastępcze.

Wysyłanie z szablonem

Ustaw pole template wysyłki na obiekt wskazujący szablon, przez id (emt_...) lub przez slug, używając dokładnie jednego z nich. Wartości zmiennych umieść w template.parameters. Dodaj language, aby wybrać konkretny język, lub pomiń go, aby wysłać w domyślnym języku szablonu, chyba że szablon wymaga wskazania języka w każdej wysyłce. Pomiń subject, html i text całkowicie, ponieważ szablon już je dostarcza.

Przykład kodu

{
  "from": "hello@yourdomain.com",
  "to": ["delivered@messagebird.dev"],
  "category": "transactional",
  "template": {
    "slug": "welcome-email",
    "parameters": { "first_name": "Jane" }
  }
}

Jedno zachowanie warte zaplanowania: kategoria szablonu jest wartością domyślną, a własna category wysyłki ją nadpisuje. Pomiń category, a wysyłka odziedziczy kategorię szablonu, więc szablon operacyjny wyśle jako transakcyjny bez powtarzania tego w każdym wywołaniu. Ustaw category, a Twoja wartość wygra. Reszta kontraktu po stronie wysyłki jest opisana w sekcji wysyłanie z szablonem.

Tworzenie szablonów poza dashboardem

Cały cykl życia jest dostępny poza dashboardem. Krok publikacji nosi tam nazwę submit i jest operacją zamieniającą wersję roboczą w kolejną opublikowaną wersję:

Przykład kodu

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 live

create zwraca szablon wraz z jego draft_version_id, którego wymaga każde polecenie dotyczące wersji i języka. --validate-only wykonuje te same testy kompletności co prawdziwy submit, ale niczego nie zamraża, więc to tani sposób na znalezienie wszystkich problemów we wszystkich językach za jednym razem. Odczyt szablonu zwraca jego metadane i stan poszczególnych języków, ale nie treść. Treść znajduje się w językach danej wersji, po jednym języku naraz.

SDK-i udostępniają ten sam cykl życia jako typowane metody w email.templates, z operacjami na wersjach i językach zagnieżdżonymi jako email.templates.versions i email.templates.versions.languages. Agent dociera do tych samych operacji przez narzędzia email_templates_* MCP.

Następne kroki

Wysyłanie e-maili: pełny payload wysyłki i sposób, w jaki wpasowują się w niego wysyłki z szablonem
Kategorie: wybór między marketing a transactional w każdej wysyłce
bird email templates: zarządzanie szablonami z terminala
Dokumentacja API: pełne schematy żądań i odpowiedzi dla wszystkich osiemnastu operacji na szablonach
SDK-i: typowane metody email.templates w TypeScript, Python, PHP i Go
Serwer MCP: umożliwienie agentowi tworzenia i publikowania szablonów
Jak stworzyć szablon e-maila: film pokazujący budowanie szablonu w dashboardzie, a następnie tworzenie kolejnego przez agenta

Powiązane zasoby

Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.

Poznaj możliwościEmail templates Podążaj ścieżką naukiBuild your first integration

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy