Statistik email API

API statistik email mengembalikan data agregat yang ditampilkan di dasbor Metrics, beserta verdict kesehatan pengiriman yang dihitung darinya. Gunakan untuk membangun dasbor, mengekspor data, atau memantau kesehatan email. Endpoint ini memerlukan kunci API dengan akses baca ke scope emails.

Metode bertipe tersedia di SDK TypeScript, Python, PHP, dan Go di bawah email.stats dan email.health, bird CLI mengeksposnya sebagai bird email stats dan bird email health, dan agen mengaksesnya melalui tool MCP email_stats_* dan email_health. Skema request dan response lengkap ada di referensi API.

Agregat dan seri waktu

Tiga endpoint mencakup bagian atas dasbor:

GET /v1/email/stats/summary mengembalikan satu baris agregat untuk seluruh window. Baris ini mencakup hitungan siklus hidup untuk accepted, delivered, bounced, complained, opened, clicked, beserta sub-tipenya. Baris ini juga mencakup turunan delivery_rate, bounce_rate, complaint_rate, open_rate, dan click_rate. Persentil latensi pemrosesan, pengiriman, dan total mencakup p50, p95, dan p99. Kirim compare=previous_period dan respons juga menyertakan window sebelumnya dengan panjang yang sama beserta perubahannya.
GET /v1/email/stats/daily dan GET /v1/email/stats/hourly mengembalikan hitungan yang sama satu baris per hari atau per jam, diisi nol pada baris kosong agar grafik tidak pernah berlubang.

Setiap rate dikembalikan sebagai pecahan antara 0 dan 1, jadi delivery_rate sebesar 0.9939 berarti 99,39%. Rate yang penyebutnya nol bernilai null, sehingga periode tanpa pengiriman melaporkan open_rate alih-alih menampilkan 0. Rate menggunakan waktu event untuk atribusi. Waktu kirim tidak memengaruhi window mana yang menyertakan suatu event, sehingga engagement yang masuk selama window untuk pesan yang lebih lama tetap disertakan. Rumus pasti di balik setiap rate, termasuk bagaimana bounce out-of-band yang terlambat mengeluarkan penerima dari hitungan delivered, didokumentasikan per field di referensi summary.

Setiap respons mengembalikan window yang dihitung, ditambah data_as_of: momen terakhir angka-angka ini berlaku. Agregasi diperbarui setiap beberapa detik, sehingga respons bersifat mendekati real-time, bukan langsung. Beri label dasbor Anda dengan data_as_of alih-alih menyajikan angka seolah akurat hingga detik.

Memilih window

from dan to menerima hari kalender (YYYY-MM-DD) atau instant RFC 3339, dan format yang diterima tiap endpoint berbeda:

Endpoint	Batas	Window maksimum
/summary	Keduanya hari, atau keduanya instant	365 hari, atau 720 jam pada instant
/daily	Hari kalender	365 hari
/hourly	Instant RFC 3339	720 jam (30 hari)

Batas instant berpresisi jam, yang menjadikan "last 24 hours" bergulir cukup satu request. Pada /summary, mencampur hari dengan instant mengembalikan 422.

Atur timezone ke identifier IANA seperti America/New_York agar batas hari dan jam, serta default yang digunakan saat Anda menghilangkan from dan to, dihitung dalam zona tersebut alih-alih UTC. Selama timezone diatur, from dan to tidak boleh menyertakan offset UTC sendiri.

Breakdown

13 endpoint breakdown memotong angka pengiriman dan engagement yang sama berdasarkan satu dimensi:

Pengirim: /sending-domains, /sending-ips, dan /recipient-domains (domain mailbox tujuan pengiriman Anda).
Tempat mendarat: /mailbox-providers (Gmail, Outlook, dan sebagainya) dan /mailbox-provider-regions.
Yang Anda kirim: /tags (tag yang Anda atur saat mengirim, potongan paling fleksibel), /categories, /templates, dan /broadcasts.
Konteks engagement: /locations (geografi penerima) dan /clients (klien email yang merender open).
Kegagalan: /bounce-codes (dikelompokkan berdasarkan respons server penerima) dan /complaint-types.

Semuanya berada di bawah /v1/email/stats/. Baris dikembalikan diurutkan menurun berdasarkan metrik sort dan dibatasi limit (default 50, maksimum 200). Respons juga menyertakan total, jumlah nilai dimensi unik dalam window. Bandingkan total dengan jumlah baris yang dikembalikan untuk mengidentifikasi hasil yang terpotong. Baris yang metrik pengurutannya adalah rate dengan penyebut nol ditempatkan di akhir.

Default sort setiap endpoint adalah metrik yang menjadi dasar peringkatnya:

Default	Breakdown
processed	/tags, /categories, /templates, /broadcasts, /sending-domains, /recipient-domains
delivered	/sending-ips, /mailbox-providers, /mailbox-provider-regions
unique_opens	/locations, /clients
bounced	/bounce-codes
complained	/complaint-types

include_trend=true menambahkan seri rate per bucket ke setiap baris, siap untuk sparkline. Ini berlaku untuk breakdown tag, category, template, sending-domain, sending-IP, recipient-domain, mailbox-provider, dan mailbox-provider-region.

Endpoint summary dan seri waktu juga menerima satu filter dimensi per request. Pilih category, sending_domain, sending_ip, recipient_domain, tag, atau template. Filter ini membatasi agregat ke satu pengirim atau kampanye tanpa beralih ke breakdown. Mengirim lebih dari satu mengembalikan 422.

Kesehatan pengiriman

GET /v1/email/health menjawab pertanyaan yang tidak dijawab oleh data agregat: apakah pengiriman Anda menuju masalah. Endpoint ini mengembalikan satu verdict untuk jendela waktu beserta sinyal untuk pengiriman, open, bounce, dan complaint. Setiap sinyal memuat rate dan verdict-nya. Sinyal pengiriman, bounce, dan complaint juga memuat batas yang menentukan verdict-nya; open rate tidak memiliki batas risiko. Inilah yang memungkinkan badge status mengikuti band kami tanpa salinan yang dikompilasi ke dalam klien Anda sendiri.

Contoh kode

{
  "period": {
    "data_as_of": null,
    "from": "2026-05-25",
    "to": "2026-06-01"
  },
  "status": "watching",
  "signals": [
    {
      "metric": "delivery_rate",
      "value": 0.995,
      "limit": null,
      "status": "healthy",
      "thresholds": {
        "direction": "below",
        "throttled": 0.984,
        "watching": 0.99
      }
    },
    {
      "metric": "open_rate",
      "value": 0.20100503,
      "limit": null,
      "status": "healthy"
    },
    {
      "metric": "bounce_rate",
      "value": 0.005,
      "limit": 0.005,
      "status": "watching",
      "thresholds": {
        "direction": "above",
        "throttled": 0.006,
        "watching": 0.004
      }
    },
    {
      "metric": "complaint_rate",
      "value": 0.00010050251,
      "limit": 0.003,
      "status": "healthy",
      "thresholds": {
        "direction": "above",
        "throttled": 0.001,
        "watching": 0.0006
      }
    }
  ]
}

Cocokkan setiap sinyal berdasarkan metric-nya. status tingkat atas adalah yang terburuk dari verdict pengiriman, bounce, dan complaint: healthy, watching, atau throttled. open_rate berada di luar roll-up tersebut, karena open rate tinggi bukan risiko, dan sinyal ini satu-satunya yang dapat bernilai strong.

Dua field pada sinyal mudah tertukar. limit adalah batas deliverability referensi untuk rate tersebut, dan bernilai null pada rate yang tidak memilikinya. thresholds adalah tempat verdict berubah: watching dan throttled adalah dua batasnya, dan direction menyebutkan sisi berisiko dari keduanya, above untuk bounce rate dan complaint rate serta below untuk delivery rate. Batas bersifat eksklusif, jadi rate yang tepat berada di batas tetap mendapat status yang lebih baik.

Karena batas dikembalikan dalam respons, Anda dapat menilai irisan yang tidak dihitung endpoint ini: urutkan pengirim Anda dengan /sending-domains, lalu klasifikasikan setiap baris terhadap batas bounce rate yang dikembalikan respons kesehatan. Dasbor Metrics menggunakan band peringatan terpisah untuk hard-bounce rate dan complaint rate. API ini mengevaluasi bounce rate, complaint rate, dan delivery rate agregat, sehingga verdict-nya bisa berbeda dari peringatan dasbor.

Verdict throttled melaporkan risiko deliverability. Verdict ini tidak menghentikan pengiriman Anda.

Jendela waktu bekerja berbeda dari endpoint di atas. from dan to adalah hari kalender dalam UTC, tidak ada parameter timezone, dan tidak ada filter dimensi yang berlaku. Kosongkan keduanya dan jendela berakhir hari ini serta dimulai 7 hari sebelumnya. Maksimum adalah 365 hari.

Lalu lintas uji dalam angka

Pengiriman ke alamat sandbox melewati agregasi yang sama, sehingga lalu lintas uji muncul di setiap endpoint di sini persis seperti tampilannya di dasbor.

Langkah selanjutnya

Metrik email: cara dasbor menampilkan angka-angka ini dan kapan harus bertindak
Referensi ringkasan statistik: setiap field, filter, dan formula rate
Referensi kesehatan pengiriman: verdict, sinyal per rate, dan batasnya
Event dan webhook: stream per penerima ketika data agregat tidak cukup

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.

Tonton panduannyaGetting started with email Jelajahi kemampuannyaEmail Ikuti jalur pembelajaranBuild your first integration Panduan implementasiSend your first email

Coba praktiknya dan dapatkan ringkasan implementasi