Zeitgesteuerter Versand

Versand planen

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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></p>",
		Category:    bird.CategoryMarketing,
		ScheduledAt: time.Date(2027, 1, 15, 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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></p>",
    "category": "marketing",
    "scheduled_at": "2027-01-15T09:00:00Z"
  }'

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

Inline-Inhalt oder eine Vorlage zum späteren Versand einplanen

Sendezeitpunkt wählen

• Er muss zwischen 30 Sekunden und 30 Tagen in der Zukunft liegen. Näher als 30 Sekunden oder weiter als 30 Tage wird mit einem 422 abgelehnt. Die Untergrenze verhindert, dass eine geplante Nachricht mit einem sofortigen Versand konkurriert. 30 Tage sind der weiteste Horizont, für den wir eine Nachricht vorhalten.
• Geben Sie einen exakten Zeitpunkt an. Verwenden Sie einen UTC-Z (2027-01-15T09:00:00Z) oder ein explizites Offset (2026-07-30T09:00:00-04:00, derselbe Zeitpunkt wie 13:00:00Z). Wir vergleichen den Zeitpunkt mit der aktuellen Uhrzeit und interpretieren nie eine reine Ortszeit oder wenden die Zeitzone eines Empfängers an. Um um 9 Uhr in der jeweiligen Ortszeit jedes Empfängers zu senden, berechnen Sie diese Zeitpunkte selbst und planen Sie einen Versand pro Zeitzone.

Geplante Nachrichten auflisten

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_..."

Geplanten Versand stornieren

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"

• Nur eine noch geplante Nachricht kann storniert werden. Eine Nachricht, deren Versand bereits begonnen hat, die bereits gesendet oder bereits storniert wurde, gibt 409 zurück:
  Codebeispiel

  {
    "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."
    }
  }

  Wenn der Sendezeitpunkt erreicht wird, kann eine Stornierung auch das Rennen gegen den Versand selbst verlieren und aus demselben Grund 409 zurückgeben.
• Sie können den Versand stornieren, während Inhalte noch hochgeladen werden. Bei einer geplanten E-Mail mit Anhängen oder einem großen Nachrichtentext werden nach der Antwort 202 möglicherweise noch Inhalte gespeichert. Nach einer erfolgreichen Stornierung bleibt der Versand storniert, auch wenn der Upload später abgeschlossen wird.
• Stornieren gibt das Kontingent für geplante E-Mails nicht zurück. Die beim Planen verbrauchte Einheit bleibt verbraucht. Das verhindert, dass eine Planen-und-Stornieren-Schleife das Kontingent umgeht. Ihr reguläres Versandkontingent bleibt unberührt, da es erst belastet wird, wenn eine Nachricht tatsächlich gesendet wird.
• Stornieren kann sicher wiederholt werden mit einem Idempotency-Key, wie jeder andere Schreibvorgang.

Was zum Sendezeitpunkt passiert

• Payload- und Domain-Validierung laufen sofort. Ein fehlerhafter geplanter Versand schlägt beim API-Aufruf mit einem 422 fehl, sodass Sie es jetzt erfahren und nicht erst um 9 Uhr.
• Die Absenderdomain wird zum Sendezeitpunkt erneut geprüft. Wenn Ihre from-Domain zum geplanten Zeitpunkt nicht mehr verifiziert ist, wird die Nachricht nicht gesendet. Ihre Empfänger werden als rejected mit einer Begründung zurückgegeben, statt E-Mails von einer nicht verifizierten Domain zu erhalten. Halten Sie die Domain für das gesamte Zeitfenster verifiziert.
• Ihr Versandkontingent wird zum Sendezeitpunkt belastet. Das reguläre Versandkontingent wird verbraucht, wenn die Nachricht ausgelöst wird. Das Planen lässt das Kontingent unverändert. Ist das Kontingent zum Sendezeitpunkt erschöpft, werden die Empfänger abgelehnt.
• Unterdrückung wird zum Sendezeitpunkt ausgewertet, anhand Ihrer Unterdrückungsliste in ihrem dann aktuellen Stand. Jemand, der sich zwischen Planung und Versand abmeldet, wird also trotzdem berücksichtigt.
• Eine gespeicherte Vorlage muss zum Sendezeitpunkt noch existieren. Wenn Sie die Vorlage nach dem Planen löschen, wird die Nachricht nicht gesendet. Ihre Empfänger werden als rejected mit generation_failure zurückgegeben.

Fehler

Webhooks

• email.scheduled meldet eine Nachricht, die auf den zukünftigen Zeitpunkt scheduled_at wartet. Bei Vorlagen wird die ausgewählte Version zum Sendezeitpunkt erneut geladen und ihr Inhalt vorbereitet. Dieses Ereignis kann eintreffen, bevor diese Arbeit abgeschlossen ist.
• email.canceled wird ausgelöst, wenn eine geplante Nachricht vor dem Versand storniert wird.

Nächste Schritte

• E-Mail senden: der vollständige Sende-Payload und das asynchrone 202-Modell
• Unterdrückungen: an wen wir nicht zustellen und warum, ausgewertet zum Sendezeitpunkt
• Events und Webhooks: die Events, die eine geplante Nachricht nach dem Auslösen erzeugt
• Idempotenz: sichere Wiederholungen für die Planungs- und Stornierungsaufrufe
• API-Referenz: der vollständige Vertrag des Stornierungsendpunkts
• Eine E-Mail für späteren Versand planen: ein Video, das einen geplanten Versand und dessen Stornierung zeigt