Envoi programmé

Programmer un envoi

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

Un envoi programmé utilise du contenu inline

Choisir l'heure d'envoi

• L'heure doit se situer entre 30 secondes et 30 jours dans le futur. Moins de 30 secondes ou plus de 30 jours est rejeté avec un 422. Le seuil minimal empêche un envoi programmé d'entrer en concurrence avec un envoi immédiat. Trente jours est l'horizon le plus lointain pour lequel nous retenons un message.
• Fournissez un instant exact. Incluez un suffixe UTC Z (2027-01-15T09:00:00Z) ou un décalage explicite (2026-07-30T09:00:00-04:00, le même instant que 13:00:00Z). Nous comparons l'instant à l'heure courante et n'interprétons jamais une heure locale brute ni n'appliquons le fuseau horaire du destinataire. Pour envoyer à 9 h dans l'heure locale de chaque destinataire, calculez vous-même ces instants et programmez un envoi par fuseau horaire.

Lister les messages programmés

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

Annuler un envoi programmé

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"

• Seul un message encore programmé peut être annulé. Un message dont l'envoi a déjà commencé, qui a déjà été envoyé ou déjà annulé renvoie 409 :
  Exemple de code

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

  À l'approche de l'heure d'envoi, une annulation peut aussi perdre la course face à l'envoi lui-même et renvoyer 409 pour la même raison.
• Un envoi volumineux peut prendre quelques secondes avant de devenir annulable. Un envoi programmé avec des pièces jointes ou un corps volumineux est encore en cours de stockage après le 202, donc :
  1. Une annulation pendant cette fenêtre renvoie 409 et le message reste programmé.
  2. Relisez le message.
  3. S'il affiche toujours status: scheduled, réessayez l'annulation.
• L'annulation ne restitue pas l'enveloppe d'e-mails programmés. L'unité consommée au moment de la programmation reste consommée, ce qui empêche une boucle programmer-puis-annuler de contourner l'enveloppe. Votre enveloppe d'envoi normale n'est pas affectée, car elle n'est débitée que lorsqu'un message part effectivement.
• L'annulation peut être réessayée en toute sécurité avec un Idempotency-Key, comme toute autre écriture.

Ce qui se passe à l'heure d'envoi

• La validation du payload et du domaine s'effectue en amont. Un envoi programmé malformé échoue lors de l'appel API avec un 422, ce qui vous informe tout de suite plutôt qu'à 9 h.
• Le domaine de l'expéditeur est revérifié à l'heure d'envoi. Si votre domaine from n'est plus vérifié lorsque l'heure programmée arrive, le message n'est pas envoyé. Ses destinataires sont renvoyés en tant que rejected avec une raison, au lieu de recevoir un e-mail d'un domaine non vérifié. Maintenez le domaine vérifié pendant toute la fenêtre.
• Votre enveloppe d'envoi est débitée à l'heure d'envoi. Le quota d'envoi normal est consommé lorsque le message part. La programmation laisse le quota inchangé. Si l'enveloppe est épuisée à l'heure d'envoi, les destinataires sont rejetés.
• La suppression est évaluée à l'heure d'envoi, par rapport à votre liste de suppression telle qu'elle est à ce moment-là. Ainsi, une personne qui se désinscrit entre la programmation et l'envoi est bien prise en compte.

Erreurs

Webhooks

• email.scheduled se déclenche lorsqu'un message est accepté avec un scheduled_at futur, et indique cette heure.
• email.canceled se déclenche lorsqu'un message programmé est annulé avant son envoi.

Étapes suivantes

• Envoyer un e-mail : le payload d'envoi complet et le modèle asynchrone 202
• Suppressions : à qui nous ne livrons pas, et pourquoi, évalué à l'heure d'envoi
• Événements et webhooks : les événements qu'un message programmé produit une fois déclenché
• Idempotence : réessayer en toute sécurité les appels de programmation et d'annulation
• Référence API : le contrat complet de l'endpoint d'annulation
• Programmer l'envoi d'un email pour plus tard : une vidéo montrant un envoi programmé et comment l'annuler