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>",
  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"
  }'

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

Ein geplanter Versand verwendet Inline-Inhalte

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

{
  "name": "email_cancel",
  "arguments": {
    "message_id": "<message-id>"
  }
}

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.
• Ein großer Versand kann einige Sekunden brauchen, bis er stornierbar ist. Ein geplanter Versand mit Anhängen oder einem großen Body speichert nach dem 202 noch Inhalte, daher:
  1. Eine Stornierung in diesem Zeitfenster gibt 409 zurück, und die Nachricht bleibt geplant.
  2. Lesen Sie die Nachricht erneut ab.
  3. Wenn sie noch status: scheduled anzeigt, versuchen Sie die Stornierung erneut.
• 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.

Fehler

Webhooks

• email.scheduled wird ausgelöst, wenn eine Nachricht mit einem zukünftigen scheduled_at angenommen wird, und meldet diesen Zeitpunkt.
• 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