Przejdź do głównej zawartości

Maile transakcyjne (transactional_emails)

E-maile transakcyjne edytowane w panelu administracyjnym. Moduł pozwala operatorom zmieniać temat, treść i wygląd każdego e-maila transakcyjnego wysyłanego przez platformę — globalnie i osobno dla każdego kanału sprzedaży — w panelu administracyjnym, w edytorze WYSIWYG bezpiecznym dla programów pocztowych i spójnym z Page Builderem modułu CMS. Każdy e-mail jest opisany definicją rejestrowaną przez moduł, do którego należy (orders, returns, organizations, inventory…), a ta definicja dostarcza domyślny temat, domyślną treść oraz zestaw zmiennych, które logika biznesowa podstawia w chwili wysyłki.

Pojęcia​

  • Definicja (Definition) — zarejestrowany e-mail identyfikowany unikalnym code (np. order_confirmation). Zawiera moduł, do którego należy, zadeklarowane zmienne (z przykładowymi wartościami do podglądu), obsługiwane języki oraz domyślny temat i treść dostarczone przez moduł. Przy starcie jest uzgadniana z tabelą transactional_emails; osierocone definicje (gdy moduł, do którego należały, odinstalowano) są usuwane.
  • Treść (Content) — dostosowanie wprowadzone przez administratora dla danego zakresu i języka, przechowywane w transactional_email_contents. W chwili wysyłki treść jest ustalana w kolejności kanał → ustawienie globalne → wartość domyślna modułu, z przejściem na domyślny język kanału. Brak wiersza oznacza „użyj kolejnego poziomu”; Reset usuwa wiersz.
  • Bloki i szablony (Blocks & Templates) — fragmenty bezpieczne dla e-maili, do wielokrotnego użytku. Bloki są osadzane po code przez EmailInsertBlock. Szablony e-maili pozostają osobną listą w panelu administracyjnym (stosowanie i zapisywanie poza obszarem roboczym edytora); EmailInsertTemplate usunięto z palety (starsze drzewa treści nadal się wyświetlają). Systemowe bloki tworzone przy instalacji — default_email_header (pokazuje oznakowanie marki przez EmailLogo / {{var branding.logoUrl}}) i default_email_footer — są automatycznie dołączane do domyślnej treści. Systemowego bloku ani szablonu nie można usunąć: DELETE /api/v1/admin/transactional-emails/blocks/:id odpowiada 409 TRANSACTIONAL_EMAIL_SYSTEM_BLOCK (details: blockId, blockCode), a DELETE /api/v1/admin/transactional-emails/templates/:id odpowiada 409 TRANSACTIONAL_EMAIL_SYSTEM_TEMPLATE (details: templateId, templateCode), z komunikatem w języku operatora. Do zgłoszenia #638 obie były odpowiedzią 409 VALIDATION_FAILED.
  • Oznakowanie marki (Branding) — logo w nagłówku, kolor wyróżniający oraz kody domyślnych bloków nagłówka i stopki, ustalane dla każdego zakresu przez moduł ustawień (transactional_emails.*). Ustalone logo jest dostępne w każdym e-mailu jako {{var branding.logoUrl}}.
  • Zmienne (Variables) — dyrektywy w stylu Magento 2 w treści i temacie: {{var path}}, {{if path}}…{{/if}}, {{for alias in list}}…{{/for}}. Wartości są escapowane w treści HTML i wstawiane bez zmian w wersji tekstowej. Brakująca wartość daje pusty tekst — e-mail nigdy nie jest wysyłany z nierozwiązanym {{…}}, a brakująca zmienna nigdy nie powoduje niepowodzenia wysyłki. Edytor w panelu administracyjnym udostępnia listę Insert variable (w temacie, polach tekstowych i pasku narzędzi edytora tekstu sformatowanego), zasilaną zmiennymi zadeklarowanymi dla e-maila i kluczami oznakowania marki.

Edytor e-maili​

Edytor e-maili transakcyjnych (i newslettera) korzysta ze wspólnego EmailEditorPane:

  • Układ ekranu. Edytor e-maila transakcyjnego korzysta z układu wspólnego dla wszystkich edytorów z Page Builderem (PageBuilderEditorLayout z @endora-commerce/page-builder-admin): obszar roboczy zajmuje pełną szerokość edytora, a w jednym wierszu nad nim znajdują się Zakres (wszystkie kanały albo nadpisanie dla jednego kanału sprzedaży), Język i Temat. Inaczej niż w edytorach CMS i bloga nie ma tu zwijanego panelu ustawień — te trzy pola mówią, która wiadomość jest w obszarze roboczym, albo są jej częścią, więc nigdy nie są ukrywane. Edytory bloku e-maila i szablonu e-maila korzystają z tego samego układu z samym polem Język.
  • Paleta Puck bezpieczna dla e-maili z @endora-commerce/email-components (bez punktów przełamania CMS i bez responsywnego układania elementów jeden pod drugim). Row otwiera wybór układu kolumn (1–6 kolumn), tak jak w CMS; kolumny w chwili wysyłki tworzą stałą tabelę, a w obszarze roboczym — 12-kolumnową siatkę CMS. Column nie ma na liście palety (występuje tylko wewnątrz Row). Table to siatka danych (nagłówki i wiersze, jak SimpleTable w CMS).
  • Obszar roboczy ma stałą szerokość wiadomości (600px) i panel Outline, tak jak w CMS. Preview email otwiera okno z wyrenderowanym HTML i przykładowymi wartościami zmiennych oraz opcjami Desktop mail (600px) / Narrow (320px) (płynny kontener max-width:600px, więc wąski podgląd nie wychodzi poza okno). Save as template / Apply template korzystają z akcji nagłówka CMS, ale działają na szablonach e-maili transakcyjnych (email_templates).
  • EmailLogo pokazuje logo z oznakowania marki (bez pola na adres URL). EmailImage przyjmuje adres URL albo zasób z biblioteki mediów, tak jak w CMS. Pola kolorów korzystają ze wspólnej palety kolorów CMS. Logo w ustawieniach oznakowania marki (*_asset_id) wybiera się w selektorze Biblioteki mediów.
  • EmailRichText korzysta z edytora tekstu sformatowanego TipTap z CMS (z dodatkiem zmiennych).
  • EmailProductCard wybiera produkt z katalogu; EmailOrderSummary to przełączniki kolumn i sum i pojawia się w palecie tylko wtedy, gdy e-mail deklaruje order.items (obecnie tylko Order confirmation). Potwierdzenie zamówienia udostępnia też opisane bloki szczegółów: Order ID, Billing/Shipping address, Summary, Applied discounts, Delivery method, Payment method (każdy dostępny tylko wtedy, gdy istnieje jego zmienna szablonu).
  • Bloki treści obejmują układ (EmailSection, EmailRow/EmailColumn, tabelę, odstęp, separator), tekst (EmailText, EmailRichText, nagłówki, wyróżnienie, stopkę i informacje prawne), media (EmailImage, EmailLogo), handel (EmailProductCard, EmailOrderSummary i opisane wyżej bloki szczegółów zamówienia), EmailSocial (ikony, etykiety i włączanie każdego linku osobno) oraz EmailInsertBlock.

Renderowanie​

Renderowanie odbywa się po stronie serwera w pakiecie @endora-commerce/email-components, utrzymywanym w tym repozytorium (bez Reacta): drzewo treści Puck jest przechodzone i zamieniane na HTML oparty na tabelach, ze stylami wpisanymi w elementy, bezpieczny dla programów pocztowych, oraz na wersję tekstową. Edytor w panelu administracyjnym korzysta z tej samej palety komponentów bezpiecznych dla e-maili. HTML z EmailRichText przed wysyłką jest oczyszczany według listy dozwolonych znaczników (p/strong/em/u/a/ul/ol/li/br); znaczniki dyrektyw w tekście są zachowywane.

Rejestrowanie e-maila w module​

// manifest.ts
transactionalEmails: [
{ code: 'order_confirmation', name: 'Order confirmation', group: 'orders',
variables: [{ key: 'order.businessId', label: 'Order number', sampleValue: 'ORD-1042' }] },
],

// plugin.ts (default subject + content)
emailDefaultsRegistry.register('order_confirmation', { defaultSubject, defaultContent });

sampleValue zmiennej jest po angielsku. Gdy przykład w innym języku brzmi inaczej — adres, status — dodaj sampleValueKey: klucz we własnych pakietach tłumaczeń modułu, który deklaruje zmienną (względny wobec jego przestrzeni nazw, jak labelKey akcji palety), z przykładem w każdym dostarczanym języku; wpis angielski jest równy sampleValue. Lista zmiennych i podgląd na żywo w edytorze oraz podgląd po stronie serwera pokazują przykład w edytowanym języku; gdy klucz się nie rozwiązuje, obowiązuje sampleValue z manifestu.

Moduł, do którego należy e-mail, wysyła go przez port TransactionalEmailSender (wstrzykiwany przez kompozycję), zachowując dotychczasową idempotentność opartą na messageId:

await sender.send({
code: 'order_confirmation',
salesChannelId, language, to,
messageId: `order_confirmation:${order.id}`,
variables: { order: { businessId, items: [...] }, customer: { firstName } },
});

Gdy nadawca nie jest podłączony, moduły wracają do starszych mechanizmów budowania wiadomości w kodzie, więc w środowiskach bez tego modułu zachowanie się nie zmienia.

Moduł, który zachowuje też mechanizm zastępczy w kodzie, korzysta zamiast tego z portu templateEmailPort, którego trySend odpowiada false tylko wtedy, gdy dla danego kodu nie ma definicji. Przyjmuje te same code, to, messageId i variables, a opcjonalnie także kanał sprzedaży odbiorcy (salesChannelId) i jego język (language): wiadomość jest renderowana z treści tego kanału w tym języku. Brakujący albo usunięty kanał oznacza domyślny kanał systemu, a brakujący język — domyślny język kanału, więc wywołanie bez żadnego z nich dostaje domyślny kanał systemu w jego domyślnym języku. E-mail o ponownej dostępności przekazuje kanał i język zapisane w subskrypcji.

Podgląd​

POST /api/v1/admin/transactional-emails/{code}/preview renderuje e-mail z zadeklarowanymi przykładowymi wartościami wszystkich zmiennych (i z ewentualną niezapisaną treścią roboczą), zwracając { subject, html, text }. Panel administracyjny otwiera HTML w nowej karcie.

Wyłączanie e-maila​

Samego modułu nie da się wyłączyć: każde wdrożenie wysyła przez niego weryfikację konta, zaproszenia i wiadomości dotyczące zamówień, więc /platform/modules pokazuje go jako zablokowany, z tym powodem, zamiast przełącznika. Wyłączać można natomiast pojedyncze e-maile — lista na /transactional-emails ma przełącznik w każdym wierszu, obsługiwany przez POST /api/v1/admin/transactional-emails/{code}/activation z { active }. Przełączenie przechodzi przez Command Bus, więc jest audytowane jako transactional_email.activation.set i odwracalne; nie usuwa treści, nadpisań ani dostosowań dla kanałów. Wyłączony e-mail w chwili wysyłki odpowiada { status: 'deactivated' } i nie jest wysyłana żadna wiadomość zastępcza.

E-maili potrzebnych do założenia konta lub odzyskania do niego dostępu w ogóle nie można wyłączyć: obecnie są to email_verification i organization_invitation. Deklaracja znajduje się we wpisie rejestru modułu, do którego należy e-mail (EmailDefaults.nonDeactivatable), a nie na liście utrzymywanej przez ten moduł czy panel administracyjny, a odrzucone przełączenie zwraca 409 TRANSACTIONAL_EMAIL_NOT_DEACTIVATABLE z powodem podanym przez ten moduł — w tej samej postaci, jakiej używa odmowa na poziomie modułu.

Zapis dostarczenia​

Każda wysyłka pozostawia jeden wiersz w email_deliveries — tabeli należącej do modułu email: o losie wiadomości decyduje transport, więc tam znajduje się zapis tego losu. Wiersz zawiera odbiorcę, kod e-maila, kanał sprzedaży, identyfikator wiadomości, dokument biznesowy, który wiadomość dostarczała (zwykle fakturę), wynik i czas próby.

Wynik jest jednym z czterech, a ten podział jest istotą tabeli:

StatusZnaczenieTypowy powód
sentserwer pocztowy przyjął wiadomość—
loggednie skonfigurowano serwera pocztowego (SMTP_URL nie jest ustawione), więc wiadomość została jedynie zapisana w logu serwera i do nikogo nie dotarła—
suppressedplatforma celowo jej nie wysłaładeactivated (operator wyłączył ten e-mail), duplicate_message_id
failedwiadomość miała zostać wysłana i nie zostałatransport_error, no_transport, no_definition

Operator, który pyta, „czy klient dostał fakturę”, dostaje więc odpowiedź, która przetrwa rotację logów i nie myli konfiguracji, którą sam wybrał, z awarią. Wiadomość ze statusem logged nigdy nie jest zgłaszana jako wysłana: nadawca odpowiada logged modułowi, który o nią poprosił, więc faktura wystawiona na instancji bez serwera pocztowego informuje, że e-mail nie został wysłany, a przypomnienie, które trafiłoby do dzwonka i na e-mail, jest zapisywane jako dostarczone wyłącznie do dzwonka. To dostarczanie bez gwarancji, ale z trwałym zapisem, a nie dostarczanie gwarantowane: nie ma kolejki ponowień ani skrzynki nadawczej (outbox), ponowna wysyłka pozostaje działaniem operatora, a wiadomość utracona między zapisem biznesowym a wywołaniem transportu przepada. Tabela nie ma jeszcze ekranu w panelu administracyjnym — odczytuje się ją bezpośrednio z bazy danych.

Gdy konto klienta jest anonimizowane, moduł customers prosi moduł email (emailDeliveryAnonymizationPort) o wyczyszczenie każdego zapisu zaadresowanego na adres tego konta, porównywany bez rozróżniania wielkości liter: odbiorca zostaje zastąpiony znacznikiem anonimizacji, a temat, koperta i treść błędu serwera pocztowego są usuwane; identyfikator wiadomości, kod e-maila, status, powód, kanał sprzedaży, odwołanie do dokumentu i czas próby zostają. Każdy wyczyszczony zapis dostaje jeden wpis audytu email_delivery.anonymized.

Uprawnienia​

  • transactional_emails:read — przeglądanie e-maili, bloków, szablonów, oznakowania marki i podglądu.
  • transactional_emails:write — edycja treści i oznakowania marki oraz zarządzanie blokami i szablonami.

Zarejestrowane e-maile​

Przez ten mechanizm przechodzą wszystkie wcześniejsze e-maile transakcyjne: zamówienia (potwierdzenie, komentarz, ponowne zamówienie, zamówienie utworzone przez administratora), zwroty (zaakceptowany, odrzucony), organizacje (weryfikacja, zaproszenie, nowa rejestracja, zatwierdzenie, odrzucenie) oraz magazyn (niski stan, ponowna dostępność). Zarejestrowano też dwa nowe e-maile wysyłane przez subskrybentów zdarzeń: płatności (payment_status_changed, przy otrzymaniu lub niepowodzeniu płatności) i przesyłki (shipment_created, przy utworzeniu przesyłki).

Inne moduły rejestrują własne: koszyki (cart_approval_requested, cart_approved, cart_rejected), faktury (invoice_issued), zapytania ofertowe (quote_request_pdf oraz jedenaście e-maili powiadomień quote_request_customer_* / quote_request_operator_*), CRM (crm_event_reminder), projekty (projects_stage_deadline_alert) i zadania (tasks_task_reminder, tasks_daily_digest). To, które z nich widać w danej instancji, zależy od zainstalowanych modułów.