# 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](/docs/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

```bash
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](/docs/guides/email/templates) 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:

```bash
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:

```yaml
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](/docs/guides/email/templates): Templates in jeder Sprache erstellen, vorschauen und veröffentlichen
- [`bird email templates check`](/docs/cli/reference/email-templates-check): alle Flags des Befehls
- [Die `bird` CLI](/docs/cli): eine fixierte Version installieren und in CI authentifizieren

## Related resources

- [Getting started with email](/learn/email/getting-started-with-email) (video)
- [Email](/email-api) (product)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=email)