Sign inGet Started

Kirim email pertama Anda

Buat kunci API, kirim melalui domain onboarding bersama milik Bird, lalu periksa hasilnya. Untuk panduan ini, Anda tidak perlu memverifikasi domain pengirim atau memublikasikan catatan DNS. Verifikasi domain Anda sendiri sebelum mengirim ke pelanggan.

1. Buat kunci API

Di dashboard, buka Platform tools > API keys lalu buat kunci. Setiap kunci terikat pada satu region dan berbentuk bk_us1_... atau bk_eu1_.... Region pada prefiks menunjukkan host API yang perlu Anda panggil: https://us1.platform.bird.com atau https://eu1.platform.bird.com.

Halaman API Keys di dashboard Bird, yang menampilkan daftar kunci beserta prefiks tersamar, cakupan, dan waktu terakhir digunakan

Kunci lengkap hanya ditampilkan sekali, saat dibuat. Salin ke tempat yang aman, lalu ekspor agar cuplikan kode di langkah 2 dapat membacanya:

Contoh kode
export BIRD_API_KEY="bk_us1_..."

2. Kirim email

Kirim dari onboarding@messagebird.dev, domain onboarding bersama milik Bird yang tersedia di workspace Anda tanpa pengaturan apa pun. Tujukan ke delivered@messagebird.dev, penerima sandbox yang selalu berhasil menerima, sehingga hasilnya pasti tanpa memerlukan kotak surat sungguhan.

Panggilan cURL menggunakan host US. Jika kunci Anda diawali bk_eu1_, panggil https://eu1.platform.bird.com sebagai gantinya. SDK membaca region dari kunci Anda dan memilih host-nya. Tab TypeScript memerlukan npm install @messagebird/sdk.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  subject: "Hello from Bird",
  html: "<p>My first Bird email.</p>",
});

console.log(msg.id, msg.status);

Untuk langkah instalasi dan menjalankan kode secara lengkap di setiap bahasa atau framework, gunakan quickstart SDK.

3. Lihat hasilnya

API merespons dengan 202: Bird telah menerima pengiriman untuk diproses secara asinkron. Periksa status pengiriman secara terpisah. Kolom *_count melacak penerima melalui setiap status pengiriman. Pada respons awal, satu penerima berstatus diterima dan belum ada yang terkirim.

Contoh kode
{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "onboarding@messagebird.dev" },
  "to": [{ "email": "delivered@messagebird.dev" }],
  "subject": "Hello from Bird",
  "accepted_count": 1,
  "processed_count": 0,
  "delivered_count": 0,
  "deferred_count": 0,
  "bounced_count": 0,
  "complained_count": 0,
  "rejected_count": 0,
  "open_count": 0,
  "click_count": 0,
  "track_opens": true,
  "track_clicks": true,
  "created_at": "2026-07-23T13:58:20.866Z"
}

Ambil pesan berdasarkan ID em_ untuk melihat statusnya saat ini. Pesan berpindah dari accepted melalui processed ke delivered. Lakukan polling hingga pesan sandbox mencapai delivered:

const msg = await bird.email.get("em_abc123");
msg.status; // "accepted" | "processed" | "delivered" | "bounced" | …
msg.delivered_count;
msg.bounced_count;
console.log(msg.subject, msg.subject_recipient_id);

Di tab cURL, ganti {region} dan {message_id}, lalu gunakan $BIRD_API_KEY sebagai pengganti $TOKEN.

Hasil pembacaan kini menampilkan status: "delivered", delivered_count: 1, dan stempel waktu delivered_at. Lihat panduan peristiwa untuk mengetahui apa yang dibuktikan oleh delivered bagi penerima sungguhan.

Karena Anda mengirim ke delivered@messagebird.dev, hasilnya sudah pasti: pesan melewati jalur pengiriman Bird yang sebenarnya, termasuk format peristiwa dan webhook produksi, tetapi tidak pernah sampai ke kotak surat sungguhan. Untuk menguji bounce, kirim ke bounce@messagebird.dev. Panduan sandbox pengujian mencantumkan setiap alamat sandbox beserta hasil simulasinya.

Tentang domain onboarding

Pengirim bersama onboarding@messagebird.dev tersedia untuk onboarding dan memiliki batasan berikut:

  • Selain alamat sandbox @messagebird.dev, pengirim ini hanya mengirim ke anggota workspace Anda yang terverifikasi; penerima lain ditolak dengan 422.
  • Pengiriman dibatasi 50 penerima per organisasi per hari UTC, dengan menghitung setiap alamat to, cc, dan bcc, termasuk penerima sandbox. Jika batas terlampaui, API mengembalikan 429.

Saat Anda siap mengirim email ke pelanggan sungguhan, verifikasi domain pengirim Anda sendiri dan masukkan alamat Anda sendiri di from; bagian lain dari permintaan tetap sama.

Langkah berikutnya