Invio programmato

Programmare un invio

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 invio programmato usa contenuto inline

Scegliere l'orario di invio

• Deve essere tra 30 secondi e 30 giorni nel futuro. Meno di 30 secondi o più di 30 giorni viene rifiutato con un 422. Il limite inferiore impedisce a una programmazione di competere con un invio immediato. Trenta giorni è l'orizzonte massimo per cui tratteniamo un messaggio.
• Fornisci un istante esatto. Includi un suffisso UTC Z (2027-01-15T09:00:00Z) o un offset esplicito (2026-07-30T09:00:00-04:00, lo stesso istante di 13:00:00Z). Confrontiamo l'istante con l'ora corrente e non interpretiamo mai un'ora locale senza offset né applichiamo il fuso orario del destinatario. Per inviare alle 9:00 nell'ora locale di ciascun destinatario, calcola tu quegli istanti e programma un invio per fuso orario.

Elencare i messaggi programmati

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

Annullare un invio programmato

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"

• Solo un messaggio ancora programmato può essere annullato. Un messaggio che ha già iniziato l'invio, è già stato inviato o è già stato annullato restituisce 409:
  Esempio di codice

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

  All'avvicinarsi dell'orario di invio, un annullamento può anche perdere la corsa con l'invio stesso e restituire 409 per lo stesso motivo.
• Un invio di grandi dimensioni può impiegare alcuni secondi prima di diventare annullabile. Un invio programmato con allegati o un body di grandi dimensioni sta ancora salvando il contenuto dopo 202, quindi:
  1. Un annullamento in quella finestra restituisce 409 e il messaggio resta programmato.
  2. Rileggi il messaggio.
  3. Se mostra ancora status: scheduled, riprova l'annullamento.
• L'annullamento non restituisce l'unità della quota di email programmate. L'unità consumata al momento della programmazione resta consumata: è ciò che impedisce a un ciclo programma-e-annulla di aggirare la quota. La tua quota di invio regolare non viene toccata, perché viene addebitata solo quando un messaggio viene effettivamente inviato.
• L'annullamento è sicuro da riprovare con un Idempotency-Key, come qualsiasi altra scrittura.

Cosa succede al momento dell'invio

• La validazione del payload e del dominio avviene subito. Un invio programmato malformato fallisce nella chiamata API con un 422, così lo scopri ora e non alle 9 di mattina.
• Il dominio del mittente viene ricontrollato al momento dell'invio. Se il tuo dominio from non è più verificato quando arriva l'orario programmato, il messaggio non viene inviato. I suoi destinatari vengono restituiti come rejected con un motivo, invece di ricevere email da un dominio non verificato. Mantieni il dominio verificato per tutta la finestra.
• La quota di invio viene addebitata al momento dell'invio. La quota di invio regolare viene consumata quando il messaggio parte. La programmazione lascia la quota invariata. Se la quota è esaurita al momento dell'invio, i destinatari vengono rifiutati.
• La soppressione viene valutata al momento dell'invio, in base alla tua lista di soppressione così com'è in quel momento, quindi chi si disiscrive tra la programmazione e l'invio viene comunque rispettato.

Errori

Webhook

• email.scheduled viene emesso quando un messaggio è accettato con un scheduled_at futuro e riporta quell'orario.
• email.canceled viene emesso quando un messaggio programmato viene annullato prima dell'invio.

Passi successivi

• Invio email: il payload di invio completo e il modello asincrono 202
• Soppressioni: a chi non consegniamo e perché, valutato al momento dell'invio
• Eventi e webhook: gli eventi prodotti da un messaggio programmato dopo la partenza
• Idempotenza: riprovare in sicurezza le chiamate di programmazione e annullamento
• Riferimento API: il contratto completo dell'endpoint di annullamento
• Programmare l'invio di un'email in un secondo momento: un video che mostra un invio programmato e come annullarlo