Pengiriman terjadwal

Atur scheduled_at untuk menahan pesan hingga waktu tertentu. Saat waktu itu tiba, pesan memasuki siklus pengiriman normal dan menghasilkan event yang sama seperti pengiriman langsung. Aplikasi Anda tidak perlu menjalankan scheduler sendiri.

Menjadwalkan pengiriman

Tambahkan timestamp scheduled_at ke pengiriman POST /v1/email/messages biasa. Tidak ada yang berubah pada payload selain itu.

const msg = await bird.email.send({
  from: "news@yourdomain.com",
  to: ["delivered@messagebird.dev"],
  subject: "Your weekly digest",
  html: "<p>Here is what happened this week...</p>",
  category: "marketing",
  scheduled_at: "2027-01-15T09:00:00Z",
});
console.log(msg.id, msg.status); // "em_…", "accepted"

msg = client.email.send(
    from_="news@yourdomain.com",
    to=["delivered@messagebird.dev"],
    subject="Your weekly digest",
    html="<p>Here is what happened this week...</p>",
    category="marketing",
    scheduled_at="2027-01-15T09:00:00Z",
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	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:        "news@yourdomain.com",
		To:          []string{"delivered@messagebird.dev"},
		Subject:     "Your weekly digest",
		HTML:        "<p>Here is what happened this week...</p>",
		Category:    bird.CategoryMarketing,
		ScheduledAt: time.Date(2026, 7, 30, 9, 0, 0, 0, time.UTC),
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$message = $bird->email->send(
    from: 'news@yourdomain.com',
    to: ['delivered@messagebird.dev'],
    subject: 'Your weekly digest',
    html: '<p>Here is what happened this week...</p>',
    category: 'marketing',
    scheduledAt: new \DateTimeImmutable('2027-01-15T09:00:00Z'),
);
echo $message->getId(), ' ', $message->getStatus();

bird email send \
  --from news@yourdomain.com \
  --to delivered@messagebird.dev \
  --subject 'Your weekly digest' \
  --html '<p>Here is what happened this week...</p>' \
  --category marketing \
  --scheduled-at 2027-01-15T09:00:00Z

curl -X POST https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "news@yourdomain.com",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your weekly digest",
    "html": "<p>Here is what happened this week...</p>",
    "category": "marketing",
    "scheduled_at": "2027-01-15T09:00:00Z"
  }'

Panggilan ini langsung mengembalikan 202 Accepted dengan message ID berawalan em_ dan status: accepted. Objek pesan yang dikembalikan sama dengan yang dihasilkan pengiriman langsung, ditambah scheduled_at dalam UTC, sehingga Anda dapat mengonfirmasi waktu kirim tanpa pembacaan tambahan. Penerimaan bersifat sinkron; pengiriman ditunda. Hilangkan scheduled_at dari permintaan dan pesan langsung terkirim, serta responsnya tidak memuat key scheduled_at.

Pada endpoint pembacaan, pesan menampilkan status: scheduled beserta scheduled_at hingga waktu kirim tiba:

Contoh kode

{
  "id": "em_01ky7q24hafjgvzfg02v3m177p",
  "status": "scheduled",
  "scheduled_at": "2027-01-15T09:00:00Z",
  "category": "marketing"
}

Saat waktunya tiba, kami melepas pesan dan statusnya bergerak melalui state biasa (accepted, lalu processed, lalu delivered, dan seterusnya). scheduled_at tetap terisi setelahnya, sehingga Anda selalu dapat melihat kapan pesan dijadwalkan.

Penjadwalan mengonsumsi satu unit dari kuota email terjadwal organisasi Anda untuk periode penagihan tersebut. Melebihi kuota ini ditolak dengan 422 (E10003).

Pengiriman terjadwal menggunakan konten inline

scheduled_at dan template bersifat saling eksklusif, dan pengiriman yang menyetel keduanya ditolak dengan 422. Itulah ketentuannya: pengiriman terjadwal memiliki subject dan body sendiri, sedangkan pengiriman template langsung terkirim. Untuk menjadwalkan konten template, render subject dan body-nya terlebih dahulu. Dashboard dan bird CLI menampilkan pratinjau subject, HTML, dan teks persis yang akan dikirim oleh pengiriman template. Jadwalkan nilai hasil render tersebut sebagai konten inline.

Item batch menerima scheduled_at dengan ketentuan yang sama, sehingga satu batch dapat mencampur pesan terjadwal dan langsung. Setiap item terjadwal mengonsumsi unit kuota masing-masing, dan seluruh batch ditolak jika waktu salah satu item di luar rentang. Setiap item terjadwal membawa scheduled_at sendiri dalam respons batch, dan item yang langsung terkirim tidak memiliki key scheduled_at; referensi batch menunjukkan keduanya dalam satu respons.

Payload pengiriman langsung tetap bisa terlalu besar untuk dijadwalkan. Jika body, daftar penerima, atau metadata melebihi batas penjadwalan, API mengembalikan 422. Kurangi field tersebut atau kirim pesan secara langsung.

Memilih waktu kirim

scheduled_at adalah timestamp absolut RFC 3339. Dua aturan mengaturnya:

Harus antara 30 detik dan 30 hari ke depan. Kurang dari 30 detik atau lebih dari 30 hari ditolak dengan 422. Batas bawah ini mencegah jadwal bersaing dengan pengiriman langsung. Tiga puluh hari adalah horizon terjauh kami menahan pesan.
Berikan momen yang tepat. Sertakan Z UTC (2027-01-15T09:00:00Z) atau offset eksplisit (2026-07-30T09:00:00-04:00, momen yang sama dengan 13:00:00Z). Kami membandingkan momen tersebut terhadap waktu saat ini dan tidak pernah menginterpretasi waktu lokal tanpa offset atau menerapkan zona waktu penerima. Untuk mengirim pukul 9 pagi di waktu lokal masing-masing penerima, hitung momen tersebut sendiri dan jadwalkan satu pengiriman per zona waktu.

Ekspresi relatif seperti "in 2 hours" tidak diterima. Kirim timestamp yang sudah di-resolve.

Melihat daftar pesan terjadwal

Filter daftar pesan berdasarkan status untuk melihat pesan yang belum terkirim:

for await (const message of bird.email.list({ status: "scheduled" })) {
  console.log(message.id, message.scheduled_at);
}

for message in client.email.list(status="scheduled"):
    print(message.id, message.scheduled_at)

for msg, err := range client.Email.List(context.Background(), bird.EmailListParams{Status: bird.EmailStatusScheduled}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id)
}

foreach ($bird->email->list(['status' => 'scheduled']) as $message) {
    echo $message->getId(), "\n";
}

bird email list --status scheduled

curl "https://us1.platform.bird.com/v1/email/messages?status=scheduled" \
  -H "Authorization: Bearer bk_us1_..."

status=canceled menampilkan pesan yang Anda batalkan sebelum terkirim. Setelah pesan terjadwal dilepas, pesan masuk ke pipeline dan muncul dengan status pengiriman, sama seperti pengiriman lainnya. Log email di dashboard menyediakan filter Scheduled dan Canceled yang sama.

Membatalkan pengiriman terjadwal

Batalkan pesan kapan saja sebelum mulai terkirim dengan POST /v1/email/messages/{message_id}/cancel:

await bird.email.cancel("em_abc123");

client.email.cancel("em_abc123")

if err := client.Email.Cancel(context.Background(), "em_abc123"); err != nil {
	log.Fatal(err)
}

$bird->email->cancel('em_01krdgeqcxet5s7t44vh8rt9mg');

bird email cancel <message-id> --yes

curl -X POST "https://{region}.platform.bird.com/v1/email/messages/{message_id}/cancel" \
  -H "Authorization: Bearer $TOKEN"

Pembatalan yang berhasil mengembalikan 204 No Content. Status pesan menjadi canceled, pesan tidak pernah terkirim, dan webhook email.canceled aktif. Empat hal yang perlu diketahui:

Hanya pesan yang masih terjadwal yang dapat dibatalkan. Pesan yang sudah mulai terkirim, sudah terkirim, atau sudah dibatalkan mengembalikan 409:

Contoh kode

{
  "error": {
    "type": "conflict_error",
    "code": "E10005",
    "name": "EmailNotCancelable",
    "message": "This message cannot be canceled.",
    "remediation": "Only a scheduled message that has not started sending can be canceled. Once sending begins there is no way to pull it back."
  }
}

Saat waktu kirim tiba, pembatalan juga bisa kalah cepat dari pengiriman itu sendiri dan mengembalikan 409 dengan alasan yang sama.

Pengiriman besar bisa memerlukan beberapa detik sebelum bisa dibatalkan. Pengiriman terjadwal dengan lampiran atau body besar masih menyimpan konten setelah 202, sehingga:
1. Pembatalan dalam jendela waktu itu mengembalikan 409 dan pesan tetap terjadwal.
2. Baca kembali pesan tersebut.
3. Jika masih menampilkan status: scheduled, coba lagi pembatalannya.
Pembatalan tidak mengembalikan kuota email terjadwal. Unit yang Anda konsumsi saat menjadwalkan tetap terpakai, dan inilah yang mencegah pola jadwalkan-lalu-batalkan untuk mengelabui kuota. Kuota pengiriman reguler Anda tidak terpengaruh, karena kuota itu baru dikenakan saat pesan benar-benar terkirim.
Pembatalan aman untuk dicoba lagi dengan Idempotency-Key, seperti operasi tulis lainnya.

Untuk memindahkan pengiriman terjadwal ke waktu lain, batalkan lalu kirimkan pengiriman baru dengan scheduled_at yang baru. Anda mendapatkan ID em_ baru.

Apa yang terjadi saat waktu kirim

Penjadwalan hanya mengubah kapan pesan dilepas. Konstruksi dan aturannya tetap sama. Lampiran, kategori, tag, dan metadata semuanya berperilaku persis seperti pada pengiriman langsung, dan ditampilkan pada event webhook dengan cara yang sama. Empat pemeriksaan terbagi di dua momen:

Validasi payload dan domain dilakukan di awal. Pengiriman terjadwal yang salah format gagal pada panggilan API dengan 422, sehingga Anda mengetahuinya sekarang, bukan saat pukul 9 pagi.
Domain pengirim diperiksa ulang saat waktu kirim. Jika domain from Anda sudah tidak terverifikasi saat waktu terjadwal tiba, pesan tidak dikirim. Penerimanya dikembalikan sebagai rejected dengan alasan, alih-alih menerima email dari domain yang tidak terverifikasi. Pastikan domain tetap terverifikasi selama seluruh jendela waktu.
Kuota pengiriman dikenakan saat waktu kirim. Kuota pengiriman reguler dikonsumsi saat pesan dilepas. Penjadwalan tidak mengubah kuota. Jika kuota habis saat waktu kirim, penerima ditolak.
Supresi dievaluasi saat waktu kirim, berdasarkan daftar supresi Anda pada saat itu, sehingga seseorang yang berhenti berlangganan antara penjadwalan dan pengiriman tetap dihormati.

Error

Status	Kode	Kapan
422	E10003	Kuota email terjadwal organisasi Anda untuk periode penagihan sudah habis
422		scheduled_at kurang dari 30 detik atau lebih dari 30 hari ke depan
422		scheduled_at dikombinasikan dengan template
422		Payload terlalu besar untuk ditahan; kurangi body, penerima, atau metadata, atau kirim sekarang
409	E10005	Pesan tidak dapat dibatalkan lagi: sudah mulai terkirim, sudah terkirim, atau sudah dibatalkan
404		Tidak ada pesan dengan ID tersebut di workspace ini

Webhook

Dua event khusus untuk penjadwalan, di atas event pengiriman biasa:

email.scheduled aktif saat pesan diterima dengan scheduled_at di masa depan, dan melaporkan waktu tersebut.
email.canceled aktif saat pesan terjadwal dibatalkan sebelum terkirim.

Saat pesan dilepas, rantai email.accepted normal berjalan tanpa perubahan.

Langkah selanjutnya

Mengirim email: payload pengiriman lengkap dan model async 202
Supresi: siapa yang tidak kami kirimi, dan alasannya, dievaluasi saat waktu kirim
Event dan webhook: event yang dihasilkan pesan terjadwal setelah dilepas
Idempotensi: coba lagi yang aman untuk panggilan jadwal dan batal
Referensi API: kontrak lengkap endpoint pembatalan
Jadwalkan email untuk dikirim nanti: video yang menunjukkan pengiriman terjadwal dan cara membatalkannya

Sumber daya terkait

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

Jelajahi kemampuannyaScheduled email Ikuti jalur pembelajaranBuild your first integration

Dapatkan ringkasan implementasi