# Memeriksa template email di CI

`bird email templates check` memeriksa template email Anda dari sistem CI mana pun dan keluar dengan kegagalan jika suatu perubahan akan merusaknya, sehingga pull request menangkap masalah sebelum penerima menemukannya. Perintah ini hanya membaca: tidak ada yang dikirim dan tidak ada perubahan draf.

## Sebelum Anda mulai

- Instal [`bird` CLI](/docs/cli) dengan versi yang dipatok, agar rilis baru tidak pernah mengubah pipeline Anda tanpa pemberitahuan.
- Buat kunci API dengan akses baca ke `email_management` dan sediakan untuk job sebagai `BIRD_API_KEY`.

## Memeriksa template

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

Perintah ini merender draf setiap template dalam setiap bahasa yang dimilikinya, karena terjemahan bisa rusak sendiri, dan melaporkan per template dan bahasa:

- **Dukungan klien email**: temuan kompatibilitas yang sama seperti yang ditampilkan [pratinjau template](/docs/guides/email/templates), misalnya CSS yang dihapus atau diabaikan oleh klien.
- **Ukuran**: body HTML dibandingkan dengan titik pemotongan Gmail sekitar 102 KB. Gmail menyembunyikan semua yang melewati batas itu di balik tautan. Di atas 90 KB pemeriksaan memberi peringatan, karena nilai merge bisa mendorong pesan melewati batas.
- **Tautan dan gambar**: setiap URL `http` dan `https` dalam tautan (`<a>` dan `<area>`), sumber gambar atau `srcset`, atribut `background`, atau CSS `url()` dalam atribut `style` atau blok `<style>`, diambil dari tempat perintah dijalankan. `404`, `410`, atau `5xx`, atau host yang tidak ada, adalah masalah. `401`, `403`, atau `429`, atau pencarian DNS yang kehabisan waktu, adalah peringatan, karena biasanya berarti runner ditolak atau tidak bisa menjangkau host. Tautan ke alamat privat atau loopback tidak pernah diambil. Gunakan `--skip-links` pada runner tanpa akses jaringan keluar.

Tautan yang dibangun dari variabel template, field kontak, atau tautan berhenti berlangganan tidak diambil, karena pratinjau tidak bisa mengisinya dengan nilai yang diterima penerima. Laporan mencantumkannya di bawah `unverified_links`, dengan bagian per-penerima ditampilkan sebagai `{variable}`, dan `--annotations github` mencetaknya sebagai pemberitahuan agar pull request menunjukkan apa yang tidak diperiksa.

Perintah ini mencetak laporan JSON ke stdout: `valid` untuk keseluruhan proses, lalu satu entri per template dan bahasa dengan `findings`-nya. Setiap temuan memiliki `severity`, `area` (`compatibility`, `size`, atau `links`), `message`, dan biasanya `fix`. `problem` menggagalkan pemeriksaan; `warning` dilaporkan dan tidak pernah menggagalkannya.

## Memeriksa file yang dirender oleh build Anda

Jika build Anda merender template sendiri, misalnya dengan MJML atau React Email, periksa file yang dihasilkannya:

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

File dipratinjau sebagai konten yang belum disimpan terhadap template yang Anda tentukan, jadi tidak ada perubahan draf; template apa pun bisa digunakan. Dengan `--annotations github`, temuan kompatibilitas ditempatkan pada baris file yang dirujuknya, dan temuan ukuran serta tautan dianotasi pada file secara keseluruhan.

## Kode keluar

Kode keluar adalah dasar percabangan job CI Anda:

| Kode keluar | Arti                                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| `0`         | Tidak ada masalah. Peringatan mungkin tetap dilaporkan.                                                   |
| `7`         | Pemeriksaan berjalan dan menemukan setidaknya satu masalah. Laporan menyebutkan masing-masing.            |
| `3`         | Template yang Anda tentukan tidak ada di workspace ini.                                                   |
| `4`         | Kunci API tidak ada, tidak valid, atau tidak memiliki akses baca ke `email_management`.                   |
| `6`         | Terkena pembatasan laju permintaan atau kesalahan server sementara. Coba lagi setelah jeda `retry_after`. |

Mencoba lagi pada `7` tanpa perubahan akan gagal dengan cara yang sama, jadi hanya `6` yang layak dicoba lagi.

## Menjalankannya di GitHub Actions

Dengan `--annotations github`, perintah mencetak temuan sebagai anotasi GitHub Actions alih-alih laporan JSON, sehingga muncul di pemeriksaan pull request. Workflow ini memeriksa template yang dirender oleh build Anda pada setiap pull request yang mengubahnya:

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

Atur `BIRD_CLI_VERSION` sebagai variabel repositori ke rilis yang telah Anda uji, dan secret `BIRD_API_KEY` ke kunci dengan akses baca ke `email_management`. GitHub tidak memberikan secret repositori ke pull request dari fork, sehingga workflow melewatinya. Periksa perubahan dari fork sebelum menggabungkannya dengan mendorong perubahan yang sama ke cabang di repositori Anda. Di sistem CI lain, jalankan perintah yang sama dan gagalkan job pada kode keluar bukan nol.

## Pemecahan masalah

- **Exit `3`.** Template tidak ada di workspace yang dimiliki kunci API. Daftar template workspace dengan `bird email templates list`.
- **Exit `4`.** Kunci tidak memiliki akses baca ke `email_management`, atau secret tidak sampai ke job.
- **Setiap tautan gagal dengan peringatan.** Runner tidak memiliki akses jaringan keluar, atau firewall memblokirnya. Jalankan dengan `--skip-links` di sana, dan periksa tautan dari runner yang bisa menjangkau internet.

## Langkah selanjutnya

- [Template email](/docs/guides/email/templates): menulis, mempratinjau, dan menerbitkan template dalam setiap bahasa
- [`bird email templates check`](/docs/cli/reference/email-templates-check): semua flag yang diterima perintah
- [`bird` CLI](/docs/cli): menginstal versi yang dipatok dan melakukan autentikasi di 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)