# E-mailtemplates controleren in CI

`bird email templates check` controleert je e-mailtemplates vanuit elk CI-systeem en stopt met een fout wanneer een wijziging ze zou breken, zodat een pull request het probleem eerder vindt dan een ontvanger. Het leest alleen: er wordt niets verstuurd en er veranderen geen concepten.

## Voordat je begint

- Installeer de [`bird` CLI](/docs/cli) met een vastgezette versie, zodat een nieuwe release je pipeline nooit onverwacht verandert.
- Maak een API-sleutel aan met leestoegang tot `email_management` en stel deze beschikbaar voor de job als `BIRD_API_KEY`.

## Een template controleren

```bash
bird email templates check welcome-email order-shipped
```

Het commando rendert het concept van elk template in elke taal die het heeft, omdat een vertaling op zichzelf kan breken, en rapporteert per template en taal:

- **E-mailclientondersteuning**: dezelfde compatibiliteitsbevindingen die [templatevoorbeeld](/docs/guides/email/templates) toont, zoals CSS die een client verwijdert of negeert.
- **Grootte**: de HTML-body vergeleken met het afknippunt van Gmail van ongeveer 102 KB. Gmail verbergt alles daarna achter een link. Boven 90 KB geeft de controle een waarschuwing, omdat samenvoegwaarden een bericht erover heen kunnen duwen.
- **Links en afbeeldingen**: elke `http`- en `https`-URL in een link (`<a>` en `<area>`), een afbeeldingsbron of `srcset`, een `background`-attribuut, of een CSS-`url()` in een `style`-attribuut of `<style>`-blok, opgehaald vanaf waar het commando draait. Een `404`, `410` of `5xx`, of een host die niet bestaat, is een probleem. Een `401`, `403` of `429`, of een DNS-lookup die een time-out geeft, is een waarschuwing, omdat het meestal betekent dat de runner werd geweigerd of de host niet kon bereiken. Links naar privé- of loopback-adressen worden nooit opgehaald. Gebruik `--skip-links` op een runner zonder uitgaande netwerktoegang.

Links die zijn opgebouwd uit een templatevariabele, een contactveld of de uitschrijflink worden niet opgehaald, omdat het voorbeeld ze niet kan vullen met de waarde die een ontvanger krijgt. Het rapport vermeldt ze onder `unverified_links`, met het per-ontvanger-deel weergegeven als `{variable}`, en `--annotations github` toont ze als melding zodat de pull request laat zien wat niet is gecontroleerd.

Het commando print een JSON-rapport op stdout: `valid` voor de hele run, daarna één vermelding per template en taal met zijn `findings`. Elke bevinding heeft een `severity`, een `area` (`compatibility`, `size` of `links`), een `message`, en meestal een `fix`. Een `problem` laat de controle falen; een `warning` wordt gerapporteerd en laat de controle nooit falen.

## Een bestand controleren dat je build rendert

Als je build zelf templates rendert, bijvoorbeeld met MJML of React Email, controleer dan het bestand dat het produceert:

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

Het bestand wordt als niet-opgeslagen inhoud gepreviewd tegen het template dat je opgeeft, dus er veranderen geen concepten; elk template werkt. Met `--annotations github` worden compatibiliteitsbevindingen op de regels van het bestand geplaatst waar ze naar verwijzen, en grootte- en linkbevindingen worden als annotatie op het bestand als geheel gezet.

## Exitcodes

De exitcode is waar je CI-job op vertakt:

| Exitcode | Betekenis                                                                                                        |
| -------- | ---------------------------------------------------------------------------------------------------------------- |
| `0`      | Geen problemen. Waarschuwingen kunnen alsnog worden gerapporteerd.                                               |
| `7`      | De controle heeft minstens één probleem gevonden. Het rapport benoemt elk probleem.                              |
| `3`      | Een template dat je hebt opgegeven bestaat niet in deze werkruimte.                                              |
| `4`      | De API-sleutel ontbreekt, is ongeldig, of mist leestoegang tot `email_management`.                               |
| `6`      | Beperking van het aantal verzoeken of een tijdelijke serverfout. Probeer opnieuw na de `retry_after`-vertraging. |

Opnieuw proberen bij `7` zonder een wijziging faalt op dezelfde manier, dus alleen `6` is het waard om opnieuw te proberen.

## Uitvoeren in GitHub Actions

Met `--annotations github` print het commando bevindingen als GitHub Actions-annotaties in plaats van het JSON-rapport, zodat ze verschijnen in de checks van de pull request. Deze workflow controleert de templates die je build rendert bij elke pull request die ze wijzigt:

```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"
```

Stel `BIRD_CLI_VERSION` in als repositoryvariabele met de release die je hebt getest, en het `BIRD_API_KEY`-secret als een sleutel met leestoegang tot `email_management`. GitHub geeft pull requests van forks geen repositorysecrets, dus de workflow slaat ze over. Controleer een wijziging van een fork voordat je deze merget door dezelfde wijziging naar een branch in je eigen repository te pushen. Voer in elk ander CI-systeem dezelfde commando's uit en laat de job falen bij een exitcode die niet nul is.

## Probleemoplossing

- **Exit `3`.** Het template bevindt zich niet in de werkruimte waar de API-sleutel bij hoort. Bekijk de templates van de werkruimte met `bird email templates list`.
- **Exit `4`.** De sleutel mist leestoegang tot `email_management`, of het secret bereikt de job niet.
- **Elke link faalt met een waarschuwing.** De runner heeft geen uitgaande netwerktoegang, of een firewall blokkeert het. Gebruik daar `--skip-links` en controleer links vanaf een runner die het internet kan bereiken.

## Volgende stappen

- [E-mailtemplates](/docs/guides/email/templates): templates schrijven, previewen en publiceren in elke taal
- [`bird email templates check`](/docs/cli/reference/email-templates-check): alle vlaggen die het commando accepteert
- [De `bird` CLI](/docs/cli): een vastgezette versie installeren en authenticeren in CI

## 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)