# 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](/docs/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

```bash
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](/docs/guides/email/templates) 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:

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

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

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](/docs/guides/email/templates): crie, pré-visualize e publique templates em todos os idiomas
- [`bird email templates check`](/docs/cli/reference/email-templates-check): todas as flags que o comando aceita
- [O `bird` CLI](/docs/cli): instale uma versão fixada e autentique no 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)