Gepland verzenden

Een verzending inplannen

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

Een geplande verzending gebruikt inline content

Het verzendmoment kiezen

• Het moet tussen 30 seconden en 30 dagen in de toekomst liggen. Dichter dan 30 seconden of verder dan 30 dagen wordt geweigerd met een 422. De ondergrens voorkomt dat een planning een directe verzending inhaalt. Dertig dagen is de maximale horizon waarvoor we een bericht vasthouden.
• Geef een exact tijdstip op. Gebruik een UTC-Z (2027-01-15T09:00:00Z) of een expliciet offset (2026-07-30T09:00:00-04:00, hetzelfde moment als 13:00:00Z). We vergelijken het tijdstip met de huidige tijd en interpreteren nooit een kale lokale tijd of passen de tijdzone van de ontvanger toe. Om om 9 uur 's ochtends in de lokale tijd van elke ontvanger te verzenden, bereken je die tijdstippen zelf en plan je één verzending per tijdzone in.

Geplande berichten bekijken

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

Een geplande verzending annuleren

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"

• Alleen een nog ingepland bericht kan worden geannuleerd. Een bericht dat al aan het verzenden is, al is verzonden of al is geannuleerd, retourneert 409:
  Codevoorbeeld

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

  Wanneer het verzendmoment aanbreekt, kan een annulering ook de race verliezen van de verzending zelf en om dezelfde reden 409 retourneren.
• Een grote verzending kan een paar seconden nodig hebben om annuleerbaar te worden. Een geplande verzending met bijlagen of een grote body is nog content aan het opslaan na de 202, dus:
  1. Een annulering in dat venster retourneert 409 en het bericht blijft ingepland.
  2. Lees het bericht opnieuw op.
  3. Als het nog steeds status: scheduled toont, probeer de annulering opnieuw.
• Annuleren geeft het scheduled-email-tegoed niet terug. De eenheid die je bij het inplannen hebt verbruikt, blijft verbruikt. Dat is wat voorkomt dat een inplannen-en-annuleren-loop het tegoed omzeilt. Je reguliere verzendtegoed wordt niet aangeraakt, want dat wordt pas belast wanneer een bericht daadwerkelijk wordt verzonden.
• Annuleren is veilig om opnieuw te proberen met een Idempotency-Key, net als elke andere write.

Wat er op het verzendmoment gebeurt

• Payload- en domeinvalidatie worden vooraf uitgevoerd. Een ongeldige geplande verzending faalt op de API-call met een 422, zodat je het nu ontdekt in plaats van om 9 uur 's ochtends.
• Het afzenderdomein wordt opnieuw gecontroleerd op het verzendmoment. Als je from-domein niet meer geverifieerd is wanneer het geplande tijdstip aanbreekt, wordt het bericht niet verzonden. De ontvangers worden geretourneerd als rejected met een reden, in plaats van dat er mail wordt verzonden vanaf een niet-geverifieerd domein. Houd het domein geverifieerd gedurende het hele venster.
• Je verzendtegoed wordt belast op het verzendmoment. Het reguliere verzendquotum wordt verbruikt wanneer het bericht wordt vrijgegeven. Inplannen laat het quotum ongewijzigd. Als het tegoed op het verzendmoment is uitgeput, worden de ontvangers geweigerd.
• Suppressie wordt beoordeeld op het verzendmoment, tegen je suppressielijst zoals die er op dat moment uitziet. Iemand die zich tussen inplannen en verzenden uitschrijft, wordt dus alsnog gerespecteerd.

Fouten

Webhooks

• email.scheduled wordt geactiveerd wanneer een bericht met een toekomstige scheduled_at wordt geaccepteerd, en rapporteert dat tijdstip.
• email.canceled wordt geactiveerd wanneer een gepland bericht wordt geannuleerd voordat het wordt verzonden.

Volgende stappen

• E-mail verzenden: de volledige verzendpayload en het async 202-model
• Suppressies: naar wie we niet bezorgen, en waarom, beoordeeld op het verzendmoment
• Events en webhooks: de events die een gepland bericht produceert zodra het wordt vrijgegeven
• Idempotentie: veilig opnieuw proberen voor de schedule- en cancel-calls
• API-referentie: het volledige contract van het cancel-endpoint
• Een e-mail inplannen om later te verzenden: een video die een geplande verzending en het annuleren ervan laat zien