E-Mail-Templates in CI prüfen

bird email templates check prüft Ihre E-Mail-Templates aus jedem CI-System heraus und beendet sich mit einem Fehler, wenn eine Änderung sie beschädigen würde – so erkennt ein Pull Request das Problem, bevor es ein Empfänger tut. Der Befehl liest nur: Es wird nichts gesendet und kein Entwurf geändert.

Bevor Sie beginnen

Installieren Sie die bird CLI mit einer fixierten Version, damit ein neues Release Ihre Pipeline nie unangekündigt verändert.
Erstellen Sie einen API-Schlüssel mit Lesezugriff auf email_management und stellen Sie ihn dem Job als BIRD_API_KEY zur Verfügung.

Ein Template prüfen

Codebeispiel

bird email templates check welcome-email order-shipped

Der Befehl rendert den Entwurf jedes Templates in jeder vorhandenen Sprache, da eine Übersetzung eigenständig fehlschlagen kann, und meldet pro Template und Sprache:

Mail-Client-Kompatibilität: dieselben Kompatibilitätsbefunde, die die Template-Vorschau anzeigt, etwa CSS, das ein Client entfernt oder ignoriert.
Größe: den HTML-Body gegen Gmails Clipping-Grenze von etwa 102 KB. Gmail versteckt alles darüber hinaus hinter einem Link. Ab 90 KB warnt die Prüfung, da Merge-Werte eine Nachricht über die Grenze schieben können.
Links und Bilder: jede http- und https-URL in einem Link (<a> und <area>), einer Bildquelle oder srcset, einem background-Attribut oder einer CSS-url() in einem style-Attribut oder <style>-Block, abgerufen vom Standort des Befehls. Ein 404, 410 oder 5xx oder ein nicht existierender Host ist ein Problem. Ein 401, 403 oder 429 oder ein DNS-Lookup mit Timeout ist eine Warnung, weil es in der Regel bedeutet, dass der Runner abgewiesen wurde oder den Host nicht erreichen konnte. Links zu privaten oder Loopback-Adressen werden nie abgerufen. Übergeben Sie --skip-links auf einem Runner ohne ausgehenden Netzwerkzugang.

Links, die aus einer Template-Variable, einem Kontaktfeld oder dem Abmeldelink aufgebaut sind, werden nicht abgerufen, da die Vorschau sie nicht mit dem Wert füllen kann, den ein Empfänger erhält. Der Bericht listet sie unter unverified_links auf, wobei der empfängerspezifische Teil als {variable} angezeigt wird, und --annotations github gibt sie als Hinweis aus, damit der Pull Request zeigt, was nicht geprüft wurde.

Der Befehl gibt einen JSON-Bericht auf stdout aus: valid für den gesamten Lauf, dann einen Eintrag pro Template und Sprache mit seinem findings. Jeder Befund hat einen severity, einen area (compatibility, size oder links), eine message und in der Regel einen fix. Ein problem lässt die Prüfung fehlschlagen; ein warning wird gemeldet, lässt sie aber nie fehlschlagen.

Eine von Ihrem Build gerenderte Datei prüfen

Wenn Ihr Build Templates selbst rendert, etwa mit MJML oder React Email, prüfen Sie die erzeugte Datei:

Codebeispiel

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

Die Datei wird als ungespeicherter Inhalt gegen das von Ihnen genannte Template vorgeschaut, also ohne Entwurfsänderungen; jedes Template funktioniert. Mit --annotations github landen Kompatibilitätsbefunde an den betreffenden Zeilen der Datei, und Größen- sowie Linkbefunde werden an der Datei als Ganzes annotiert.

Exit-Codes

Der Exit-Code bestimmt, wie Ihr CI-Job verzweigt:

Exit-Code	Bedeutung
0	Keine Probleme. Warnungen können dennoch gemeldet werden.
7	Die Prüfung lief und fand mindestens ein Problem. Der Bericht benennt jedes einzelne.
3	Ein von Ihnen genanntes Template existiert in diesem Workspace nicht.
4	Der API-Schlüssel fehlt, ist ungültig oder hat keinen Lesezugriff auf email_management.
6	Anfragerate begrenzt oder temporärer Serverfehler. Nach der retry_after-Verzögerung erneut versuchen.

Ein erneuter Versuch bei 7 ohne Änderung schlägt genauso fehl, daher lohnt sich nur bei 6 ein erneuter Versuch.

In GitHub Actions ausführen

Mit --annotations github gibt der Befehl Befunde als GitHub-Actions-Annotationen statt des JSON-Berichts aus, sodass sie in den Checks des Pull Requests erscheinen. Dieser Workflow prüft die von Ihrem Build gerenderten Templates bei jedem Pull Request, der sie ändert:

Codebeispiel

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"

Setzen Sie BIRD_CLI_VERSION als Repository-Variable auf das von Ihnen getestete Release und das BIRD_API_KEY-Secret auf einen Schlüssel mit Lesezugriff auf email_management. GitHub gibt Pull Requests aus Forks keine Repository-Secrets, daher überspringt der Workflow sie. Prüfen Sie eine Änderung aus einem Fork vor dem Merge, indem Sie dieselbe Änderung auf einen Branch in Ihrem Repository pushen. In jedem anderen CI-System führen Sie dieselben Befehle aus und lassen den Job bei einem Exit-Code ungleich null fehlschlagen.

Fehlerbehebung

Exit 3. Das Template befindet sich nicht in dem Workspace, zu dem der API-Schlüssel gehört. Listen Sie die Templates des Workspace mit bird email templates list auf.
Exit 4. Der Schlüssel hat keinen Lesezugriff auf email_management, oder das Secret erreicht den Job nicht.
Jeder Link schlägt mit einer Warnung fehl. Der Runner hat keinen ausgehenden Netzwerkzugang, oder eine Firewall blockiert ihn. Führen Sie dort --skip-links aus und prüfen Sie Links von einem Runner, der das Internet erreichen kann.

Nächste Schritte

E-Mail-Templates: Templates in jeder Sprache erstellen, vorschauen und veröffentlichen
bird email templates check: alle Flags des Befehls
Die bird CLI: eine fixierte Version installieren und in CI authentifizieren

Verwandte Ressourcen