Mengirim email

Pengiriman minimal

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); // "em_…", "accepted"

msg = 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(msg.id, msg.status)

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.Send(context.Background(), 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 {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$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();

bird email send \
  --from hello@yourdomain.com \
  --html '<p>It works.</p>' \
  --subject 'Hello from Bird' \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Hello from Bird",
    "html": "<p>It works.</p>"
  }'

Mengirim sebelum Anda memverifikasi domain

Menyusun payload

Penerima

Konten

Reply-to dan header kustom

• Header alamat dan platform. Atur alamat pesan melalui field khusus (from, to, cc, bcc, reply_to, subject). Nama-nama tersebut, dan header yang kami buat untuk Anda (Content-Type, Content-Transfer-Encoding, DKIM-Signature, Received, Return-Path), tidak dapat diatur di sini.
• List-Unsubscribe dan List-Unsubscribe-Post pada pengiriman marketing. Kami mengatur header berhenti berlangganan sekali klik yang sesuai standar pada pengiriman tersebut. Pada pengiriman transactional, kami membiarkan header Anda persis seperti yang Anda atur.
• Nilai apa pun yang mengandung carriage return atau line feed.

Pelacakan

Kategori dan IP pool

Referensi field

Mengirim dengan template

const msg = await bird.email.send({
  from: { email: "onboarding@messagebird.dev", name: "Bird" },
  to: ["delivered@messagebird.dev"],
  category: "transactional",
  template: {
    slug: "welcome-email",
    parameters: { first_name: "Jane" },
  },
});
console.log(msg.id, msg.status);

msg = client.email.send(
    from_={"email": "onboarding@messagebird.dev", "name": "Bird"},
    to=["delivered@messagebird.dev"],
    category="transactional",
    template="welcome-email",
    parameters={"first_name": "Jane"},
)
print(msg.id, msg.status)

msg, err := client.Email.Send(context.Background(), bird.EmailSendParams{
	From:       "onboarding@messagebird.dev",
	To:         []string{"delivered@messagebird.dev"},
	Category:   "transactional",
	Template:   "welcome-email",
	Parameters: map[string]any{"first_name": "Jane"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->email->send(
    from: 'Bird <onboarding@messagebird.dev>',
    to: ['delivered@messagebird.dev'],
    category: 'transactional',
    template: (new EmailMessageSendRequestTemplate())
        ->setSlug('welcome-email')
        ->setParameters(['first_name' => 'Jane']),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --category transactional \
  --from hello@yourdomain.com \
  --parameters '{"first_name":"Jane"}' \
  --template welcome-email \
  --to delivered@messagebird.dev

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "category": "transactional",
    "template": {
      "slug": "welcome-email",
      "parameters": { "first_name": "Jane" }
    }
  }'

• Inline atau templated, tidak keduanya. Mengirim template bersamaan dengan subject, html, atau text ditolak dengan 422. API juga menolak nilai variabel di field parameters tingkat atas; pada pengiriman template, nilai tersebut ditempatkan di template.parameters.
• bird adalah satu-satunya nama cadangan. Path placeholder yang dimulai dengan bird. merujuk data kami sendiri, seperti link berhenti berlangganan atau catatan kontak penerima, sehingga key template.parameters tidak boleh bernama bird. Semua key lain bebas Anda tentukan, dan masing-masing berupa satu kata: {"order_number": "A-1043"} mengisi {{ order_number }}.
• Template dapat dikirim sekarang atau nanti. Tambahkan scheduled_at untuk menjadwalkan pengiriman. Kami mengunci versi yang dipublikasikan, bahasa yang dipilih, dan nilai parameter saat permintaan diterima. Jika Anda menghapus template sebelum waktu pengiriman, pesan ditolak dengan generation_failure.
• Pengiriman menggunakan versi template yang dipublikasikan. Draf tidak pernah dikirim. Template yang tidak dikenal ditolak dengan 404, dan template tanpa versi yang dipublikasikan ditolak dengan 422.
• language memilih salah satu bahasa template. Hilangkan untuk mengirim bahasa default template. Minta bahasa yang tidak dimiliki template, dan pengaturan on_missing_language pada template itu sendiri yang menentukan apakah kecocokan terdekat yang dikirim atau pengiriman ditolak. Template yang mengatur language_source_required menolak pengiriman yang tidak menyebutkan bahasa sama sekali.
• Kategori template adalah default, dan milik Anda menimpanya. Hilangkan category dan pengiriman mewarisi kategori template, sehingga template transaksional tidak perlu mengulangnya di setiap panggilan.

Tag vs metadata

• tags adalah pasangan {name, value} terstruktur: maksimal 20 per pengiriman, nama maksimal 32 karakter, nilai maksimal 64, hanya huruf ASCII, angka, underscore, dan tanda hubung, dan nama unik dalam satu pengiriman. Tag adalah dimensi filter, sehingga Anda dapat memfilter daftar pesan berdasarkan tag dan memecah analitik serta rollup dasbor berdasarkan tag. Gunakan untuk label berkardinalitas rendah seperti campaign, experiment_variant, atau source.
• metadata adalah objek JSON arbitrer, maksimal 2 KB setelah diserialisasi. Kami menyimpannya, mengembalikannya pada pembacaan API, dan mengirimkannya di setiap event webhook, sehingga cocok untuk konteks yang ingin Anda terima kembali: ID internal, foreign key, payload terstruktur.

{
  "tags": [{ "name": "campaign", "value": "onboarding" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Lampiran

Arti respons 202

{
  "id": "em_01ky7ma8y2es1s2akzk53tmjn0",
  "status": "accepted",
  "category": "marketing",
  "from": { "email": "hello@yourdomain.com" },
  "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"
}

• Pembacaan mengembalikan status tanpa body. GET /v1/email/messages/{message_id} mengembalikan status pesan dan penerima, tidak pernah body html atau text. Jika penyimpanan konten diaktifkan untuk workspace, body yang disimpan tetap tersedia hingga 30 hari dari GET /v1/email/messages/{message_id}/content.
• Pembacaan bisa sedikit tertinggal dari pengiriman. 404 pada endpoint pembacaan tepat setelah 202 berarti pesan belum terlihat, jadi coba lagi sesaat kemudian.

Mencoba ulang dengan aman

Pengiriman batch

Penagihan

Langkah selanjutnya

• Template email: buat dan publikasikan template yang Anda kirim di sini
• Kategori: bagaimana marketing dan transactional mengubah perilaku supresi
• Supresi: kepada siapa kami tidak mengirim, dan alasannya
• Pengiriman terjadwal: kirim pada waktu mendatang dengan scheduled_at
• Sandbox pengujian: penerima sandbox dan pengiriman sebelum verifikasi
• Referensi API: skema request dan respons lengkap