Baza wiedzy

Szablony

Treść napisana raz, wersjonowana i wysyłana wiele razy: z edytora wiadomości, z własnego kodu albo przez agenta.

Szczegóły

Szablon należy do połączenia, a nie do osoby, która go napisała — i to jest cały powód, dla którego pierwsza wersja tego mechanizmu została zastąpiona. Tamta była kluczowana po użytkowniku: szablon kolegi z zespołu był niewidoczny dla klucza API przestrzeni roboczej, więc integracja nie mogła wysłać tego, co widziała osoba, która ją skonfigurowała, a usunięcie konta autora zabierało ze sobą szablony przestrzeni roboczej. Wiersze zostały przeniesione, a nie porzucone.
Dwa sposoby tworzenia treści. Drzewo bloków zbudowane z komponentów @react-email/components (Section, Row, Column, Container, Text, Heading, Button, Link, Img, Hr, Markdown, CodeBlock, CodeInline), sprawdzane w trakcie pisania, więc błędny węzeł albo niebezpieczny href zostaje odrzucony już przy wywołaniu, które go zapisało, zamiast dotrzeć jako zepsuty e-mail. Albo znaczniki wyrenderowane samodzielnie: jeśli Twoje szablony to już komponenty react-email we własnym repozytorium, wyrenderuj je tam przez @react-email/render i wyślij HTML, który jest czyszczony raz, przy publikacji wersji.
Dwadzieścia trzy punkty wyjścia i jeden pusty, w galerii, a nie w menu, bo to rzeczy, na które trzeba spojrzeć, zanim się między nimi wybierze, więc każda karta pokazuje sam e-mail. Powitania i weryfikacje, potwierdzenia i faktury, wysyłki i odnowienia, podsumowania i ogłoszenia, ułożone pod czterema nagłówkami, a każdy otwiera się w edytorze wizualnym, w którym każdy element można przesunąć, przestylować i usunąć. Cokolwiek wybierzesz, trafia jako wersja robocza, więc nic nie nadaje się do wysyłki, dopóki tego nie opublikujesz.
Galeria to jedyna część tego mechanizmu dostępna wyłącznie w aplikacji. Wywołanie sięgające po szablony z Twojego kodu albo od agenta przesyła treść (dokument blokowy albo własne znaczniki), a nie nazwę punktu wyjścia, więc te dwadzieścia trzy pozycje są miejscem, od którego można zacząć, a nie katalogiem do instalowania.
Nazwane sloty i nazwane propsy to dwa rodzaje miejsc do wypełnienia, zapisywane jako {{key}} w treści i w temacie. Slot wypełnia ten, kto edytuje szablon, i ma wartość domyślną, więc wysyłka, która nic nie podaje, i tak się wyrenderuje. Props podaje się przy wysyłce, a ten oznaczony jako wymagany odrzuca wysyłkę, gdy go zabraknie: 422 i żadna poczta nie wychodzi. Ta odmowa jest właśnie celem zadeklarowania go: alternatywą jest wiadomość wychodząca z pustym miejscem tam, gdzie powinien być numer zamówienia — czego nic nie zgłasza i czego nikt nie cofnie.
Opublikowana wersja jest zamrożona. Edycja treści opublikowanego szablonu tworzy nową wersję roboczą, zamiast nadpisywać to, co działa na żywo, więc wysyłki nadal rozwiązują to, co rozwiązywały wczoraj, dopóki ktoś nie opublikuje, a wysyłka przypięta do numeru wersji pozostaje nietknięta nawet wtedy. Treść jest kompilowana przy publikacji, dzięki czemu szablon, który się nie renderuje, zawodzi u osoby publikującej, a nie u odbiorcy.
Podgląd renderuje dokładnie to, co dałaby wysyłka, niczego nie wysyłając, i zgłasza, co jest jeszcze puste, zamiast odmawiać. Szablon w podglądzie to zwykle szablon w trakcie pisania, a autor wypełniający blok po bloku nie powinien musieć spełnić każdego propsa, żeby zobaczyć, co ma do tej pory.
Każdy szablon prowadzi własny zapis tego, co wysłał: ile wyszło w ciągu ostatnich siedmiu, trzydziestu albo dziewięćdziesięciu dni, które z nich otwarto, a w których kliknięto, szereg dzień po dniu oraz podział według tego, skąd pochodziła każda wysyłka: z edytora wiadomości, z Twojego kodu, od agenta albo z kolejki. Każdy wskaźnik podaje własny mianownik, zamiast pożyczać cudzy, bo są naprawdę różne: otwarcia liczy się względem wiadomości, które niosły piksel, kliknięcia względem wiadomości, które niosły przepisany link, a wiadomość może nieść jedno bez drugiego. Podgląd nie jest rejestrowany w ogóle, a wysyłka testowa liczona jest osobno i pomijana w każdej liczbie, bo nigdy nie opuściła systemu.
Ten zapis uczciwie mówi o tym, czego nie widzi — i dlatego można ufać tej połowie, którą widzi. Wysyłkę łączy się z jej zapisem doręczenia przez samą wysyłkę, a taki zapis niesie tylko poczta wysłana z Twojego kodu albo z kolejki. Wiadomość wysłana z edytora wiadomości, przez agenta albo przez asystenta go nie niesie. Dlatego szablon używany głównie z edytora wiadomości trafia tu z większością wysyłek niepołączonych, a liczba niepołączonych pokazywana jest jako osobna liczba, zamiast być wliczana jako „nikt nie otworzył”.
Cztery powierzchnie nad jedną usługą, żeby pytanie „co znaczy opublikować” miało jedną odpowiedź, a nie trzy, które dziś się zgadzają. Przycisk Templates w edytorze wiadomości proponuje te opublikowane i ZASTĘPUJE wiadomość tym, co wybierzesz, zamiast wkleić to do niej: wysyłka wskazuje szablon, wersja zostaje przypięta w chwili wyboru, a treść jest renderowana tam, gdzie ją napisano, więc publikacja między wyborem a kliknięciem nie może zmienić tego, co wychodzi, a układ, którego edytor wiadomości nie utrzymałby, zostaje nienaruszony. To, co tam wypełniasz, to wartości, a nie treść. /templates to dziewięć endpointów za zakresami templates:read i templates:write, opakowanych metoda po metodzie przez SDK. Wysłanie szablonu wymaga uprawnienia do wysyłki obok uprawnienia do szablonów, więc klucz wydany narzędziu copywriterskiemu może tworzyć i publikować, nie mogąc nikomu nic wysłać. Serwer MCP udostępnia pięć narzędzi: listowanie, odczyt, podgląd, tworzenie i wysyłkę. Celowo nie ma narzędzia do aktualizacji, usunięcia ani opublikowania istniejącego szablonu. Edycja tworzy wersję roboczą, do której kolejna wysyłka i tak by nie trafiła, a usunięcia nie da się cofnąć. Edycja zapisanej treści to ekran: /workspace/templates zawiera płótno blokowe z paletą i inspektorem, obok żywy podgląd, a Save i Publish są osobnymi czynnościami — i to właśnie sprawia, że opublikowaną wersję można zostawić w spokoju, pracując nad następną.
200 szablonów na połączenie, dokument blokowy ograniczony do 500 bloków, osiem poziomów zagnieżdżenia, 20 000 znaków w pojedynczej wartości oraz 100 slotów i 100 propsów; treść przesłana jako znaczniki ograniczona do miliona znaków, a temat do 998. Każde z nich jest zabezpieczeniem przed rozbieganym skryptem, a nie limitem planu, każde odmawia komunikatem podającym liczbę, na której odmówiło, i nic w szablonach nie jest zamknięte za wyższym planem.