Wysyłanie zaplanowane

Planowanie wysyłki

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

Zaplanowana wysyłka używa treści inline

Wybór czasu wysyłki

• Musi przypadać między 30 sekund a 30 dni w przyszłości. Bliżej niż 30 sekund lub dalej niż 30 dni oznacza odrzucenie z błędem 422. Dolna granica zapobiega wyścigowi z wysyłką natychmiastową. Trzydzieści dni to najdalszy horyzont, przez który przechowujemy wiadomość.
• Podaj dokładny moment. Dołącz sufiks UTC Z (2027-01-15T09:00:00Z) lub jawne przesunięcie (2026-07-30T09:00:00-04:00, ten sam moment co 13:00:00Z). Porównujemy podany moment z bieżącym czasem i nigdy nie interpretujemy samego czasu lokalnego ani nie stosujemy strefy czasowej odbiorcy. Aby wysłać o 9:00 w czasie lokalnym każdego odbiorcy, oblicz te momenty samodzielnie i zaplanuj osobną wysyłkę dla każdej strefy.

Wyświetlanie zaplanowanych wiadomości

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

Anulowanie zaplanowanej wysyłki

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"

• Anulować można tylko wiadomość wciąż zaplanowaną. Wiadomość, której wysyłka już się rozpoczęła, która została już wysłana lub już anulowana, zwraca 409:
  Przykład kodu

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

  W momencie nadejścia czasu wysyłki anulowanie może też przegrać wyścig z samą wysyłką i zwrócić 409 z tego samego powodu.
• Duża wysyłka może potrzebować kilku sekund, zanim będzie można ją anulować. Zaplanowana wysyłka z załącznikami lub dużą treścią wciąż zapisuje zawartość po 202, więc:
  1. Anulowanie w tym oknie zwraca 409, a wiadomość pozostaje zaplanowana.
  2. Odczytaj wiadomość ponownie.
  3. Jeśli wciąż pokazuje status: scheduled, spróbuj ponownie anulować.
• Anulowanie nie zwraca jednostki limitu zaplanowanych e-maili. Jednostka zużyta w momencie planowania pozostaje zużyta, co uniemożliwia obchodzenie limitu przez pętlę planuj-anuluj. Twój zwykły limit wysyłek pozostaje nienaruszony, ponieważ jest naliczany dopiero wtedy, gdy wiadomość faktycznie zostaje wysłana.
• Anulowanie można bezpiecznie ponawiać z użyciem Idempotency-Key, tak jak każdą inną operację zapisu.

Co dzieje się w momencie wysyłki

• Walidacja payloadu i domeny odbywa się od razu. Nieprawidłowa zaplanowana wysyłka kończy się błędem na wywołaniu API z odpowiedzią 422, więc dowiadujesz się teraz, a nie o 9:00.
• Domena nadawcy jest ponownie sprawdzana w momencie wysyłki. Jeśli Twoja domena from nie jest już zweryfikowana w zaplanowanym momencie, wiadomość nie zostaje wysłana. Odbiorcy są zwracani jako rejected z podaniem przyczyny, zamiast otrzymać wiadomość z niezweryfikowanej domeny. Utrzymuj domenę zweryfikowaną przez cały okres oczekiwania.
• Twój limit wysyłek jest naliczany w momencie wysyłki. Zwykły limit wysyłek jest zużywany w chwili wysłania wiadomości. Zaplanowanie nie zmienia limitu. Jeśli limit jest wyczerpany w momencie wysyłki, odbiorcy są odrzucani.
• Supresja jest oceniana w momencie wysyłki, względem Twojej listy supresji w jej aktualnym stanie, więc osoba, która wypisze się między zaplanowaniem a wysyłką, jest uwzględniana.

Błędy

Webhooki

• email.scheduled jest wysyłany, gdy wiadomość zostaje przyjęta z przyszłym scheduled_at, i raportuje ten czas.
• email.canceled jest wysyłany, gdy zaplanowana wiadomość zostaje anulowana przed wysłaniem.

Następne kroki

• Wysyłanie e-maili: pełny payload wysyłki i asynchroniczny model 202
• Supresje: do kogo nie dostarczamy i dlaczego, oceniane w momencie wysyłki
• Zdarzenia i webhooki: zdarzenia generowane przez zaplanowaną wiadomość po jej wysłaniu
• Idempotentność: bezpieczne ponawianie wywołań planowania i anulowania
• Dokumentacja API: pełny kontrakt endpointu anulowania
• Zaplanuj wysyłkę e-maila na później: film pokazujący zaplanowaną wysyłkę i sposób jej anulowania