Envio agendado

Agendando um envio

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

Um envio agendado usa conteúdo inline

Escolhendo o horário de envio

• Precisa estar entre 30 segundos e 30 dias no futuro. Menos de 30 segundos ou mais de 30 dias é rejeitado com um 422. O limite mínimo impede que um agendamento dispute com um envio imediato. Trinta dias é o horizonte máximo pelo qual retemos uma mensagem.
• Forneça um instante exato. Inclua um Z UTC (2027-01-15T09:00:00Z) ou um offset explícito (2026-07-30T09:00:00-04:00, o mesmo instante que 13:00:00Z). Comparamos o instante com o horário atual e nunca interpretamos um horário local sem offset nem aplicamos o fuso horário do destinatário. Para enviar às 9h no horário local de cada destinatário, calcule esses instantes você mesmo e agende um envio por fuso horário.

Listando mensagens agendadas

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

Cancelando um envio agendado

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"

• Só uma mensagem ainda agendada pode ser cancelada. Uma mensagem que já começou a ser enviada, já foi enviada ou já foi cancelada retorna 409:
  Exemplo de código

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

  Quando o horário de envio chega, um cancelamento também pode perder a corrida para o próprio envio e retornar 409 pelo mesmo motivo.
• Um envio grande pode levar alguns segundos para se tornar cancelável. Um envio agendado com anexos ou corpo grande ainda está armazenando conteúdo após o 202, então:
  1. Um cancelamento nessa janela retorna 409 e a mensagem permanece agendada.
  2. Leia a mensagem novamente.
  3. Se ela ainda mostrar status: scheduled, tente o cancelamento novamente.
• Cancelar não devolve a cota de e-mails agendados. A unidade consumida no momento do agendamento permanece consumida, e é isso que impede que um loop de agendar e cancelar contorne a cota. Sua cota de envio regular não é afetada, porque ela só é cobrada quando a mensagem é realmente enviada.
• O cancelamento pode ser repetido com segurança usando um Idempotency-Key, como qualquer outra escrita.

O que acontece no horário de envio

• Validação de payload e domínio acontece na hora. Um envio agendado malformado falha na chamada API com um 422, então você descobre agora e não às 9h.
• O domínio do remetente é verificado novamente no horário de envio. Se o domínio from não estiver mais verificado quando o horário agendado chegar, a mensagem não é enviada. Seus destinatários retornam como rejected com um motivo, em vez de receberem e-mail de um domínio não verificado. Mantenha o domínio verificado durante toda a janela.
• Sua cota de envio é cobrada no horário de envio. A cota de envio regular é consumida quando a mensagem dispara. O agendamento não altera a cota. Se a cota estiver esgotada no horário de envio, os destinatários são rejeitados.
• A supressão é avaliada no horário de envio, com base na sua lista de supressão como ela estiver naquele momento, então alguém que cancelar a inscrição entre o agendamento e o envio ainda será respeitado.

Erros

Webhooks

• email.scheduled dispara quando uma mensagem é aceita com um scheduled_at futuro e informa esse horário.
• email.canceled dispara quando uma mensagem agendada é cancelada antes do envio.

Próximos passos

• Enviando e-mail: o payload completo de envio e o modelo assíncrono 202
• Supressões: para quem não entregamos e por quê, avaliado no horário de envio
• Eventos e webhooks: os eventos que uma mensagem agendada produz após disparar
• Idempotência: retentativas seguras para as chamadas de agendamento e cancelamento
• Referência do API: o contrato completo do endpoint de cancelamento
• Agendar um email para envio posterior: um vídeo que mostra um envio agendado e como cancelá-lo