# Verificar plantillas de correo en CI

`bird email templates check` verifica tus plantillas de correo desde cualquier sistema de CI y termina con un fallo cuando un cambio las rompería, para que un pull request detecte el problema antes que un destinatario. Solo lee: no envía nada ni modifica borradores.

## Antes de empezar

- Instala la [`bird` CLI](/docs/cli) con una versión fija, para que una nueva versión nunca cambie tu pipeline sin aviso.
- Crea una clave API con acceso de lectura a `email_management` y ponla a disposición del job como `BIRD_API_KEY`.

## Verificar una plantilla

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

El comando renderiza el borrador de cada plantilla en todos los idiomas que tiene, ya que una traducción puede romperse por separado, e informa, por plantilla e idioma:

- **Compatibilidad con clientes de correo**: los mismos hallazgos de compatibilidad que muestra la [vista previa de la plantilla](/docs/guides/email/templates), como CSS que un cliente elimina o ignora.
- **Tamaño**: el cuerpo HTML frente al punto de recorte de Gmail, de unos 102 KB. Gmail oculta todo lo que lo supere detrás de un enlace. Por encima de 90 KB la verificación advierte, ya que los valores de combinación pueden hacer que un mensaje lo supere.
- **Enlaces e imágenes**: cada URL `http` y `https` en un enlace (`<a>` y `<area>`), una fuente de imagen o `srcset`, un atributo `background`, o un `url()` de CSS en un atributo `style` o un bloque `<style>`, consultados desde donde se ejecuta el comando. Un `404`, `410` o `5xx`, o un host que no existe, es un problema. Un `401`, `403` o `429`, o una búsqueda DNS que expira, es una advertencia, porque normalmente significa que el runner fue rechazado o no pudo alcanzar el host. Los enlaces a direcciones privadas o de loopback nunca se consultan. Pasa `--skip-links` en un runner sin acceso de red saliente.

Los enlaces construidos a partir de una variable de plantilla, un campo de contacto o el enlace de cancelación de suscripción no se consultan, porque la vista previa no puede completarlos con el valor que recibe un destinatario. El informe los lista bajo `unverified_links`, con la parte por destinatario mostrada como `{variable}`, y `--annotations github` los imprime como aviso para que el pull request muestre lo que no se verificó.

El comando imprime un informe JSON en stdout: `valid` para toda la ejecución, luego una entrada por plantilla e idioma con su `findings`. Cada hallazgo tiene un `severity`, un `area` (`compatibility`, `size` o `links`), un `message` y normalmente un `fix`. Un `problem` hace fallar la verificación; un `warning` se reporta y nunca la hace fallar.

## Verificar un archivo que tu build renderiza

Si tu build renderiza las plantillas por su cuenta, por ejemplo con MJML o React Email, verifica el archivo que produce:

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

El archivo se previsualiza como contenido sin guardar contra la plantilla que indiques, así que no hay cambios en el borrador; cualquier plantilla sirve. Con `--annotations github`, los hallazgos de compatibilidad se ubican en las líneas del archivo a las que se refieren, y los hallazgos de tamaño y enlaces se anotan sobre el archivo en conjunto.

## Códigos de salida

El código de salida es lo que determina la decisión de tu job de CI:

| Código de salida | Significado                                                                                       |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| `0`              | Sin problemas. Puede haber advertencias reportadas.                                               |
| `7`              | La verificación se ejecutó y encontró al menos un problema. El informe nombra cada uno.           |
| `3`              | Una plantilla que indicaste no existe en este espacio de trabajo.                                 |
| `4`              | La clave API falta, no es válida o no tiene acceso de lectura a `email_management`.               |
| `6`              | Limitación de solicitudes o error temporal del servidor. Reintenta tras el retardo `retry_after`. |

Reintentar con `7` sin un cambio falla de la misma forma, así que solo `6` vale la pena reintentar.

## Ejecutar en GitHub Actions

Con `--annotations github`, el comando imprime los hallazgos como anotaciones de GitHub Actions en lugar del informe JSON, para que aparezcan en las verificaciones del pull request. Este workflow verifica las plantillas que tu build renderiza en cada pull request que las modifique:

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

Configura `BIRD_CLI_VERSION` como variable de repositorio con la versión que probaste, y el secreto `BIRD_API_KEY` con una clave con acceso de lectura a `email_management`. GitHub no proporciona secretos de repositorio a los pull requests desde forks, así que el workflow los omite. Para verificar un cambio de un fork antes de fusionarlo, empuja el mismo cambio a una rama en tu repositorio. En cualquier otro sistema de CI, ejecuta los mismos comandos y haz fallar el job con un código de salida distinto de cero.

## Solución de problemas

- **Exit `3`.** La plantilla no está en el espacio de trabajo al que pertenece la clave API. Lista las plantillas del espacio de trabajo con `bird email templates list`.
- **Exit `4`.** La clave no tiene acceso de lectura a `email_management`, o el secreto no está llegando al job.
- **Todos los enlaces fallan con una advertencia.** El runner no tiene acceso de red saliente, o un firewall lo bloquea. Ejecuta con `--skip-links` en ese caso, y verifica los enlaces desde un runner que pueda acceder a internet.

## Próximos pasos

- [Plantillas de correo](/docs/guides/email/templates): crea, previsualiza y publica plantillas en cada idioma
- [`bird email templates check`](/docs/cli/reference/email-templates-check): todas las opciones que acepta el comando
- [La `bird` CLI](/docs/cli): instala una versión fija y autentícate en 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)