# Vérifier les templates d'e-mail en CI

`bird email templates check` vérifie vos templates d'e-mail depuis n'importe quel système de CI et se termine en erreur quand une modification les casserait, pour qu'une pull request détecte le problème avant le destinataire. La commande ne fait que lire : rien n'est envoyé et aucun brouillon n'est modifié.

## Avant de commencer

- Installez le [`bird` CLI](/docs/cli) avec une version épinglée, pour qu'une nouvelle version ne modifie jamais votre pipeline sans prévenir.
- Créez une clé API avec un accès en lecture à `email_management` et rendez-la disponible pour le job en tant que `BIRD_API_KEY`.

## Vérifier un template

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

La commande effectue le rendu du brouillon de chaque template dans chaque langue qu'il possède, car une traduction peut casser indépendamment, et signale, par template et langue :

- **Compatibilité client mail** : les mêmes résultats de compatibilité que la [prévisualisation de template](/docs/guides/email/templates) affiche, comme du CSS qu'un client supprime ou ignore.
- **Taille** : le corps HTML comparé au seuil de troncature de Gmail, environ 102 Ko. Gmail masque tout ce qui dépasse derrière un lien. Au-dessus de 90 Ko, la vérification émet un avertissement, car les valeurs de fusion peuvent faire dépasser un message.
- **Liens et images** : chaque URL `http` et `https` dans un lien (`<a>` et `<area>`), une source d'image ou `srcset`, un attribut `background`, ou un `url()` CSS dans un attribut `style` ou un bloc `<style>`, récupérée depuis l'endroit où la commande s'exécute. Un `404`, `410` ou `5xx`, ou un hôte qui n'existe pas, constitue un problème. Un `401`, `403` ou `429`, ou une résolution DNS qui expire, constitue un avertissement, car cela signifie généralement que le runner a été refusé ou n'a pas pu atteindre l'hôte. Les liens vers des adresses privées ou de bouclage ne sont jamais récupérés. Passez `--skip-links` sur un runner sans accès réseau sortant.

Les liens construits à partir d'une variable de template, d'un champ de contact ou du lien de désinscription ne sont pas récupérés, car la prévisualisation ne peut pas les remplir avec la valeur que le destinataire reçoit. Le rapport les liste sous `unverified_links`, avec la partie propre au destinataire affichée comme `{variable}`, et `--annotations github` les affiche en tant que notice pour que la pull request montre ce qui n'a pas été vérifié.

La commande affiche un rapport JSON sur stdout : `valid` pour l'ensemble de l'exécution, puis une entrée par template et langue avec son `findings`. Chaque résultat a un `severity`, un `area` (`compatibility`, `size` ou `links`), un `message`, et généralement un `fix`. Un `problem` fait échouer la vérification ; un `warning` est signalé mais ne la fait jamais échouer.

## Vérifier un fichier généré par votre build

Si votre build génère les templates lui-même, par exemple avec MJML ou React Email, vérifiez le fichier qu'il produit :

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

Le fichier est prévisualisé comme contenu non enregistré par rapport au template que vous nommez, donc aucun brouillon n'est modifié ; n'importe quel template convient. Avec `--annotations github`, les résultats de compatibilité sont placés sur les lignes du fichier auxquelles ils se rapportent, et les résultats de taille et de liens sont annotés sur le fichier dans son ensemble.

## Codes de sortie

Le code de sortie est ce sur quoi votre job CI se branche :

| Code de sortie | Signification                                                                             |
| -------------- | ----------------------------------------------------------------------------------------- |
| `0`            | Aucun problème. Des avertissements peuvent tout de même être signalés.                    |
| `7`            | La vérification a trouvé au moins un problème. Le rapport nomme chacun d'eux.             |
| `3`            | Un template que vous avez nommé n'existe pas dans cet espace de travail.                  |
| `4`            | La clé API est manquante, invalide, ou n'a pas l'accès en lecture à `email_management`.   |
| `6`            | Limitation du débit ou erreur serveur temporaire. Réessayez après le délai `retry_after`. |

Réessayer sur `7` sans modification échoue de la même manière, donc seul `6` mérite une nouvelle tentative.

## Exécuter dans GitHub Actions

Avec `--annotations github`, la commande affiche les résultats sous forme d'annotations GitHub Actions au lieu du rapport JSON, pour qu'ils apparaissent dans les vérifications de la pull request. Ce workflow vérifie les templates générés par votre build à chaque pull request qui les modifie :

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

Définissez `BIRD_CLI_VERSION` comme variable de dépôt avec la version que vous avez testée, et le secret `BIRD_API_KEY` avec une clé ayant un accès en lecture à `email_management`. GitHub ne donne aucun secret de dépôt aux pull requests provenant de forks, donc le workflow les ignore. Vérifiez une modification provenant d'un fork avant de la fusionner en poussant la même modification sur une branche de votre dépôt. Dans tout autre système de CI, exécutez les mêmes commandes et faites échouer le job sur un code de sortie non nul.

## Dépannage

- **Exit `3`.** Le template ne se trouve pas dans l'espace de travail auquel la clé API appartient. Listez les templates de l'espace de travail avec `bird email templates list`.
- **Exit `4`.** La clé n'a pas l'accès en lecture à `email_management`, ou le secret n'atteint pas le job.
- **Tous les liens échouent avec un avertissement.** Le runner n'a pas d'accès réseau sortant, ou un pare-feu le bloque. Exécutez avec `--skip-links` dans ce cas, et vérifiez les liens depuis un runner qui peut atteindre Internet.

## Étapes suivantes

- [Templates d'e-mail](/docs/guides/email/templates) : créer, prévisualiser et publier des templates dans chaque langue
- [`bird email templates check`](/docs/cli/reference/email-templates-check) : tous les flags acceptés par la commande
- [Le `bird` CLI](/docs/cli) : installer une version épinglée et s'authentifier en 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)