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.

Kunci lengkap hanya ditampilkan sekali, saat dibuat. Salin ke tempat yang aman, lalu ekspor agar cuplikan kode di langkah 2 dapat membacanya:
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);from bird import APIError, Bird
with Bird() as client:
try:
message = client.email.send(
from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
to=["delivered@messagebird.dev"],
subject="Hello from Bird",
html="<p>My first Bird email.</p>",
)
print(message.id, message.status)
except APIError as err:
print("send failed:", err)package main
import (
"encoding/json"
"errors"
"log"
"net/http"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
http.HandleFunc("POST /send", func(w http.ResponseWriter, r *http.Request) {
msg, err := client.Email.Send(r.Context(), bird.EmailSendParams{
From: "onboarding@messagebird.dev",
To: []string{"delivered@messagebird.dev"},
Subject: "Hello from Bird",
HTML: "<p>My first Bird email.</p>",
})
if err != nil {
var apiErr *bird.APIError
if errors.As(err, &apiErr) {
http.Error(w, apiErr.Error(), apiErr.StatusCode)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusAccepted)
_ = json.NewEncoder(w).Encode(msg)
})
log.Fatal(http.ListenAndServe(":3000", nil))
}<?php
// Send your first email. Set BIRD_API_KEY in your environment, then run:
// php examples/quickstart-email.php
declare(strict_types=1);
require __DIR__ . '/../vendor/autoload.php';
use MessageBird\Bird;
$bird = new Bird(getenv('BIRD_API_KEY') ?: '');
$message = $bird->email->send(
from: 'Bird <onboarding@messagebird.dev>',
to: ['delivered@messagebird.dev'],
subject: 'Hello from Bird',
html: '<p>My first Bird email.</p>',
);
echo $message->getId(), ' ', $message->getStatus(), "\n";bird email send \
--from 'Bird <onboarding@messagebird.dev>' \
--html '<p>My first Bird email.</p>' \
--subject 'Hello from Bird' \
--to delivered@messagebird.devcurl -X POST "https://us1.platform.bird.com/v1/email/messages" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "onboarding@messagebird.dev", "name": "Bird" },
"to": ["delivered@messagebird.dev"],
"subject": "Hello from Bird",
"html": "<p>My first Bird email.</p>"
}'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.
{
"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);message = client.email.get("em_abc123")
print(message.id, message.status, message.delivered_count)
print(message.subject, message.subject_recipient_id)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Email.Get(context.Background(), "em_abc123")
if err != nil {
log.Fatal(err)
}
fmt.Println(*msg.Status, *msg.DeliveredCount)
fmt.Println(msg.Subject)
if msg.SubjectRecipientId != nil {
fmt.Println(*msg.SubjectRecipientId)
}
}$message = $bird->email->get('em_01krdgeqcxet5s7t44vh8rt9mg');
echo $message->getStatus();
echo $message->getSubject(), ' ', $message->getSubjectRecipientId();bird email get <message-id>curl -X GET "https://{region}.platform.bird.com/v1/email/messages/{message_id}" \
-H "Authorization: Bearer $TOKEN"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 dengan422. - Pengiriman dibatasi 50 penerima per organisasi per hari UTC, dengan menghitung setiap alamat
to,cc, danbcc, termasuk penerima sandbox. Jika batas terlampaui, API mengembalikan429.
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
- Panduan memulai per SDK: alur yang sama dalam bahasa dan framework Anda.
- Domain pengirim: verifikasi domain Anda sendiri untuk pengiriman produksi.
- Sandbox pengujian: semua alamat sandbox dan peristiwa yang dipicu masing-masing alamat.
- Referensi API email: skema lengkap permintaan dan respons.
- Memulai dengan email: video orientasi di dashboard, yang membahas lebih jauh daripada halaman ini dan menambahkan domain pengirim beserta catatan DNS-nya
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.