# Controllare i template email nella CI

`bird email templates check` controlla i template email da qualsiasi sistema di CI e termina con un errore quando una modifica li danneggerebbe, così la pull request intercetta il problema prima che lo faccia un destinatario. Opera in sola lettura: non viene inviato nulla e nessuna bozza viene modificata.

## Prima di iniziare

- Installa la [`bird` CLI](/docs/cli) con una versione fissata, in modo che una nuova release non modifichi mai la pipeline senza preavviso.
- Crea una chiave API con accesso in lettura a `email_management` e rendila disponibile al job come `BIRD_API_KEY`.

## Controllare un template

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

Il comando esegue il rendering della bozza di ogni template in tutte le lingue disponibili, perché una traduzione può rompersi da sola, e riporta, per template e lingua:

- **Compatibilità con i client di posta**: le stesse segnalazioni di compatibilità mostrate dall'[anteprima del template](/docs/guides/email/templates), come CSS che un client rimuove o ignora.
- **Dimensione**: il body HTML rispetto al punto di troncamento di Gmail, circa 102 KB. Gmail nasconde tutto ciò che lo supera dietro un link. Sopra i 90 KB il controllo avvisa, perché i valori di merge possono far superare il limite.
- **Link e immagini**: ogni URL `http` e `https` in un link (`<a>` e `<area>`), un'origine immagine o `srcset`, un attributo `background`, o un `url()` CSS in un attributo `style` o un blocco `<style>`, recuperati dalla posizione in cui viene eseguito il comando. Un `404`, `410` o `5xx`, oppure un host inesistente, è un problema. Un `401`, `403` o `429`, oppure un lookup DNS che va in timeout, è un avviso, perché di solito significa che il runner è stato rifiutato o non ha potuto raggiungere l'host. I link verso indirizzi privati o di loopback non vengono mai recuperati. Passa `--skip-links` su un runner senza accesso di rete in uscita.

I link costruiti da una variabile del template, un campo contatto o il link di disiscrizione non vengono recuperati, perché l'anteprima non può riempirli con il valore che riceve il destinatario. Il report li elenca sotto `unverified_links`, con la parte specifica del destinatario mostrata come `{variable}`, e `--annotations github` li stampa come avviso affinché la pull request mostri cosa non è stato controllato.

Il comando stampa un report JSON su stdout: `valid` per l'intera esecuzione, poi una voce per template e lingua con il suo `findings`. Ogni segnalazione ha un `severity`, un `area` (`compatibility`, `size` o `links`), un `message` e di solito un `fix`. Un `problem` fa fallire il controllo; un `warning` viene riportato ma non lo fa mai fallire.

## Controllare un file generato dalla build

Se la build genera i template autonomamente, ad esempio con MJML o React Email, controlla il file prodotto:

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

Il file viene visualizzato in anteprima come contenuto non salvato rispetto al template indicato, quindi nessuna bozza viene modificata; qualsiasi template funziona. Con `--annotations github`, le segnalazioni di compatibilità vengono associate alle righe del file a cui si riferiscono, mentre le segnalazioni su dimensione e link vengono annotate sul file nel suo complesso.

## Codici di uscita

Il codice di uscita è ciò su cui il job di CI si basa per decidere:

| Codice di uscita | Significato                                                                                        |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| `0`              | Nessun problema. Possono comunque essere riportati degli avvisi.                                   |
| `7`              | Il controllo è stato eseguito e ha trovato almeno un problema. Il report li elenca uno per uno.    |
| `3`              | Un template indicato non esiste in questo spazio di lavoro.                                        |
| `4`              | La chiave API è mancante, non valida o non ha accesso in lettura a `email_management`.             |
| `6`              | Limitazione delle richieste o errore temporaneo del server. Riprova dopo il ritardo `retry_after`. |

Riprovare con `7` senza una modifica produce lo stesso errore, quindi vale la pena riprovare solo con `6`.

## Eseguirlo in GitHub Actions

Con `--annotations github`, il comando stampa le segnalazioni come annotazioni di GitHub Actions invece del report JSON, così appaiono nei controlli della pull request. Questo workflow controlla i template generati dalla build a ogni pull request che li modifica:

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

Imposta `BIRD_CLI_VERSION` come variabile del repository con la release che hai testato e il secret `BIRD_API_KEY` con una chiave che ha accesso in lettura a `email_management`. GitHub non fornisce secret del repository alle pull request provenienti da fork, quindi il workflow le salta. Controlla una modifica da un fork prima di farne il merge spingendo la stessa modifica su un branch nel tuo repository. In qualsiasi altro sistema di CI, esegui gli stessi comandi e fai fallire il job con un codice di uscita diverso da zero.

## Risoluzione dei problemi

- **Exit `3`.** Il template non è nello spazio di lavoro a cui appartiene la chiave API. Elenca i template dello spazio di lavoro con `bird email templates list`.
- **Exit `4`.** La chiave non ha accesso in lettura a `email_management` oppure il secret non sta raggiungendo il job.
- **Tutti i link falliscono con un avviso.** Il runner non ha accesso di rete in uscita oppure un firewall lo blocca. Eseguilo con `--skip-links` in quel caso e controlla i link da un runner che può raggiungere internet.

## Prossimi passi

- [Template email](/docs/guides/email/templates): crea, visualizza in anteprima e pubblica template in ogni lingua
- [`bird email templates check`](/docs/cli/reference/email-templates-check): tutti i flag accettati dal comando
- [La `bird` CLI](/docs/cli): installare una versione fissata e autenticarsi nella 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)