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

Esempio di codice

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, 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:

Esempio di codice

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:

Esempio di codice

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: crea, visualizza in anteprima e pubblica template in ogni lingua
bird email templates check: tutti i flag accettati dal comando
La bird CLI: installare una versione fissata e autenticarsi nella CI

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Guarda la guidaGetting started with email Esplora la funzionalitàEmail Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Prova l'esercitazione e ottieni un brief di implementazione