Sprawdzanie szablonów e-mail w CI

bird email templates check sprawdza szablony e-mail z dowolnego systemu CI i kończy się błędem, gdy zmiana mogłaby je uszkodzić, więc pull request wychwytuje problem, zanim zrobi to odbiorca. Polecenie tylko odczytuje: nic nie jest wysyłane i żadne wersje robocze się nie zmieniają.

Zanim zaczniesz

Zainstaluj bird CLI z przypiętą wersją, aby nowe wydanie nigdy nie zmieniło Twojego pipeline'u bez zapowiedzi.
Utwórz klucz API z dostępem do odczytu email_management i udostępnij go zadaniu jako BIRD_API_KEY.

Sprawdzanie szablonu

Przykład kodu

bird email templates check welcome-email order-shipped

Polecenie renderuje wersję roboczą każdego szablonu we wszystkich jego językach, ponieważ tłumaczenie może się zepsuć niezależnie, i raportuje dla każdego szablonu i języka:

Obsługa klientów poczty: te same wyniki zgodności, które pokazuje podgląd szablonu, np. CSS usuwany lub ignorowany przez klienta.
Rozmiar: treść HTML porównana z punktem obcinania Gmaila wynoszącym ok. 102 KB. Gmail ukrywa wszystko powyżej tego limitu za linkiem. Powyżej 90 KB sprawdzenie zgłasza ostrzeżenie, ponieważ wartości merge mogą przepchnąć wiadomość ponad limit.
Linki i obrazy: każdy URL http i https w linku (<a> i <area>), źródle obrazu lub srcset, atrybucie background albo CSS url() w atrybucie style lub bloku <style>, pobierany z miejsca uruchomienia polecenia. 404, 410 lub 5xx, albo host, który nie istnieje, to problem. 401, 403 lub 429, albo zapytanie DNS, które przekroczyło limit czasu, to ostrzeżenie, ponieważ zwykle oznacza, że runner został odrzucony lub nie mógł dotrzeć do hosta. Linki do adresów prywatnych lub loopback nie są pobierane. Użyj --skip-links na runnerze bez wychodzącego dostępu do sieci.

Linki zbudowane ze zmiennej szablonu, pola kontaktu lub linku rezygnacji z subskrypcji nie są pobierane, ponieważ podgląd nie może wypełnić ich wartością, którą otrzyma odbiorca. Raport wymienia je w sekcji unverified_links, z częścią per odbiorca wyświetlaną jako {variable}, a --annotations github drukuje je jako powiadomienie, aby pull request pokazywał, co nie zostało sprawdzone.

Polecenie drukuje raport JSON na stdout: valid dla całego przebiegu, a następnie po jednym wpisie na szablon i język z jego findings. Każde znalezisko ma severity, area (compatibility, size lub links), message i zwykle fix. problem powoduje niepowodzenie sprawdzenia; warning jest raportowane i nigdy nie powoduje niepowodzenia.

Sprawdzanie pliku renderowanego przez Twój build

Jeśli Twój build sam renderuje szablony, na przykład za pomocą MJML lub React Email, sprawdź plik, który generuje:

Przykład kodu

bird email templates check --html dist/welcome.html --template welcome-email --annotations github

Plik jest podglądany jako niezapisana treść względem szablonu, który wskażesz, więc wersje robocze się nie zmieniają; dowolny szablon zadziała. Z --annotations github wyniki zgodności trafiają na linie pliku, do których się odnoszą, a wyniki dotyczące rozmiaru i linków są oznaczane na pliku jako całości.

Kody wyjścia

Kod wyjścia to wartość, na której opiera się Twoje zadanie CI:

Kod wyjścia	Znaczenie
0	Brak problemów. Ostrzeżenia nadal mogą być zgłaszane.
7	Sprawdzenie przebiegło i znalazło co najmniej jeden problem. Raport wymienia każdy z nich.
3	Szablon, który wskazałeś, nie istnieje w tym obszarze roboczym.
4	Klucz API nie istnieje, jest nieprawidłowy lub nie ma dostępu do odczytu email_management.
6	Ograniczenie liczby żądań lub tymczasowy błąd serwera. Spróbuj ponownie po opóźnieniu retry_after.

Ponowne uruchomienie przy 7 bez wprowadzenia zmiany kończy się tak samo, więc warto ponawiać tylko 6.

Uruchamianie w GitHub Actions

Z --annotations github polecenie drukuje wyniki jako adnotacje GitHub Actions zamiast raportu JSON, więc pojawiają się one w sprawdzeniach pull requesta. Ten workflow sprawdza szablony renderowane przez Twój build przy każdym pull requeście, który je zmienia:

Przykład kodu

name: Email templates
on:
  pull_request:
    paths: ["emails/**"]
jobs:
  check:
    # Pull requests from forks get no repository secrets, so the check could only exit 4.
    if: ${{ !github.event.pull_request.head.repo.fork }}
    runs-on: ubuntu-latest
    env:
      BIRD_API_KEY: ${{ secrets.BIRD_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Install the bird CLI
        run: curl -fsSL https://cli.bird.com/install.sh | sh -s -- --version "${{ vars.BIRD_CLI_VERSION }}"
      - name: Build the templates
        run: npm ci && npm run build:emails
      - name: Check the templates
        run: |
          status=0
          for file in dist/emails/*.html; do
            bird email templates check --html "$file" --template welcome-email --annotations github || status=$?
          done
          exit "$status"

Ustaw BIRD_CLI_VERSION jako zmienną repozytorium na wydanie, które przetestowałeś, a sekret BIRD_API_KEY na klucz z dostępem do odczytu email_management. GitHub nie udostępnia pull requestom z forków sekretów repozytorium, więc workflow je pomija. Sprawdź zmianę z forka przed mergem, wypychając tę samą zmianę do gałęzi w swoim repozytorium. W każdym innym systemie CI uruchom te same polecenia i zakończ zadanie błędem przy niezerowym kodzie wyjścia.

Rozwiązywanie problemów

Wyjście 3. Szablon nie znajduje się w obszarze roboczym, do którego należy klucz API. Wylistuj szablony obszaru roboczego za pomocą bird email templates list.
Wyjście 4. Klucz nie ma dostępu do odczytu email_management lub sekret nie dociera do zadania.
Każdy link kończy się ostrzeżeniem. Runner nie ma wychodzącego dostępu do sieci lub blokuje go zapora. Użyj --skip-links w tym środowisku, a linki sprawdzaj z runnera, który ma dostęp do internetu.

Następne kroki

Szablony e-mail: twórz, podglądaj i publikuj szablony we wszystkich językach
bird email templates check: wszystkie flagi polecenia
bird CLI: instalacja przypiętej wersji i uwierzytelnianie w CI

Powiązane zasoby

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

Obejrzyj przewodnikGetting started with email Poznaj możliwościEmail Podążaj ścieżką naukiBuild your first integration Przewodnik wdrożeniowySend your first email

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy