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

Codevoorbeeld

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

Codevoorbeeld

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:

Codevoorbeeld

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: templates schrijven, previewen en publiceren in elke taal
bird email templates check: alle vlaggen die het commando accepteert
De bird CLI: een vastgezette versie installeren en authenticeren in CI

Gerelateerde bronnen

Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.

Bekijk de gidsGetting started with email Ontdek de mogelijkheidEmail Volg het leerpadBuild your first integration ImplementatiegidsSend your first email

Probeer de oefening en ontvang een implementatieoverzicht