Verificar templates de e-mail no CI

bird email templates check verifica seus templates de e-mail a partir de qualquer sistema de CI e encerra com falha quando uma alteração os quebraria, para que um pull request detecte o problema antes do destinatário. O comando apenas lê: nada é enviado e nenhum rascunho é alterado.

Antes de começar

Instale o bird CLI com uma versão fixada, para que uma nova versão nunca altere seu pipeline sem aviso.
Crie uma chave API com acesso de leitura a email_management e disponibilize-a para o job como BIRD_API_KEY.

Verificar um template

Exemplo de código

bird email templates check welcome-email order-shipped

O comando renderiza o rascunho de cada template em todos os idiomas que ele possui, já que uma tradução pode quebrar sozinha, e reporta, por template e idioma:

Compatibilidade com clientes de e-mail: as mesmas descobertas de compatibilidade que a pré-visualização do template mostra, como CSS que um cliente remove ou ignora.
Tamanho: o corpo HTML comparado ao ponto de corte do Gmail, de aproximadamente 102 KB. O Gmail oculta tudo além desse ponto atrás de um link. Acima de 90 KB a verificação emite um aviso, já que valores de merge podem empurrar a mensagem além do limite.
Links e imagens: toda URL http e https em um link (<a> e <area>), uma fonte de imagem ou srcset, um atributo background, ou um url() CSS em um atributo style ou bloco <style>, buscada a partir de onde o comando é executado. Um 404, 410 ou 5xx, ou um host que não existe, é um problema. Um 401, 403 ou 429, ou uma consulta DNS que expira, é um aviso, porque geralmente significa que o runner foi recusado ou não conseguiu alcançar o host. Links para endereços privados ou de loopback nunca são buscados. Passe --skip-links em um runner sem acesso de rede de saída.

Links construídos a partir de uma variável de template, um campo de contato ou o link de descadastro não são buscados, porque a pré-visualização não consegue preenchê-los com o valor que o destinatário recebe. O relatório os lista em unverified_links, com a parte por destinatário exibida como {variable}, e --annotations github os imprime como aviso para que o pull request mostre o que não foi verificado.

O comando imprime um relatório JSON no stdout: valid para toda a execução, e depois uma entrada por template e idioma com seu findings. Cada descoberta tem um severity, um area (compatibility, size ou links), uma message e geralmente um fix. Um problem reprova a verificação; um warning é reportado e nunca a reprova.

Verificar um arquivo que seu build renderiza

Se o seu build renderiza templates por conta própria, por exemplo com MJML ou React Email, verifique o arquivo que ele produz:

Exemplo de código

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

O arquivo é pré-visualizado como conteúdo não salvo em relação ao template que você nomeia, então nenhum rascunho é alterado; qualquer template funciona. Com --annotations github, as descobertas de compatibilidade aparecem nas linhas do arquivo a que se referem, e as descobertas de tamanho e link são anotadas no arquivo como um todo.

Códigos de saída

O código de saída é o que o seu job de CI usa para decidir o próximo passo:

Código de saída	Significado
0	Nenhum problema. Avisos ainda podem ser reportados.
7	A verificação foi executada e encontrou pelo menos um problema. O relatório nomeia cada um.
3	Um template que você nomeou não existe neste espaço de trabalho.
4	A chave API está ausente, é inválida ou não tem acesso de leitura a email_management.
6	Limitação de requisições ou erro temporário do servidor. Tente novamente após o atraso de retry_after.

Tentar novamente com 7 sem uma alteração falha da mesma forma, então apenas 6 vale a pena tentar novamente.

Executar no GitHub Actions

Com --annotations github, o comando imprime as descobertas como anotações do GitHub Actions em vez do relatório JSON, para que apareçam nos checks do pull request. Este workflow verifica os templates que seu build renderiza em todo pull request que os altera:

Exemplo de código

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"

Defina BIRD_CLI_VERSION como variável de repositório com a versão que você testou, e o secret BIRD_API_KEY com uma chave com acesso de leitura a email_management. O GitHub não fornece secrets de repositório para pull requests de forks, então o workflow os ignora. Verifique uma alteração de um fork antes de fazer merge enviando a mesma alteração para um branch no seu repositório. Em qualquer outro sistema de CI, execute os mesmos comandos e reprove o job com um código de saída diferente de zero.

Solução de problemas

Exit 3. O template não está no espaço de trabalho ao qual a chave API pertence. Liste os templates do espaço de trabalho com bird email templates list.
Exit 4. A chave não tem acesso de leitura a email_management, ou o secret não está chegando ao job.
Todo link falha com um aviso. O runner não tem acesso de rede de saída, ou um firewall o bloqueia. Execute com --skip-links nesse caso, e verifique os links a partir de um runner que consiga acessar a internet.

Próximos passos

Templates de e-mail: crie, pré-visualize e publique templates em todos os idiomas
bird email templates check: todas as flags que o comando aceita
O bird CLI: instale uma versão fixada e autentique no CI

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaGetting started with email Explore a funcionalidadeEmail Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first email

Experimente na prática e obtenha um resumo de implementação