Envio agendado
Defina scheduled_at para reter uma mensagem até um horário específico. Quando esse horário chega, a mensagem entra no ciclo de vida normal de entrega e produz os mesmos eventos de um envio imediato. Sua aplicação não precisa rodar seu próprio agendador.
Agendando um envio
Adicione um timestamp scheduled_at a um envio POST /v1/email/messages normal. Nada mais no payload muda.
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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></p>",
Category: bird.CategoryMarketing,
ScheduledAt: time.Date(2027, 1, 15, 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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></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><p><a href="{{ bird.unsubscribe_url }}">Unsubscribe</a></p>' \
--category marketing \
--scheduled-at 2027-01-15T09:00:00Zcurl -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><p><a href=\"{{ bird.unsubscribe_url }}\">Unsubscribe</a></p>",
"category": "marketing",
"scheduled_at": "2027-01-15T09:00:00Z"
}'A chamada retorna 202 Accepted com o ID da mensagem prefixado por em_ e status: accepted imediatamente. É o mesmo objeto de mensagem que um envio imediato retorna, mais scheduled_at ecoado em UTC, para que você confirme o horário de envio sem uma leitura adicional. A aceitação é síncrona; a entrega é adiada. Omita scheduled_at da solicitação e a mensagem sai na hora, e a resposta não traz a chave scheduled_at.
As leituras são atualizadas de forma assíncrona. Uma mensagem que você acabou de agendar pode inicialmente retornar 404 em Obter uma mensagem e não aparecer na lista de mensagens nem no painel. Conteúdo volumoso ou anexos podem prolongar essa espera enquanto os armazenamos. Guarde o ID e scheduled_at da resposta 202 e, ao tentar novamente as leituras com esse ID, aumente o intervalo entre as tentativas. Você também pode cancelar com esse ID antes de a mensagem aparecer.
Quando uma mensagem aparece enquanto ainda aguarda o envio, as leituras mostram status: scheduled e seu scheduled_at:
{
"id": "em_01ky7q24hafjgvzfg02v3m177p",
"status": "scheduled",
"scheduled_at": "2027-01-15T09:00:00Z",
"category": "marketing"
}Quando o horário chega, liberamos a mensagem e seu status avança pelos estados habituais (accepted, depois processed, depois delivered, e assim por diante). scheduled_at permanece definido depois disso, para que você sempre veja para quando a mensagem foi agendada.
O envio de uma mensagem pode começar antes que as leituras sejam atualizadas, então você pode ver primeiro um status posterior. Não há um prazo fixo que garanta que a mensagem apareça em uma leitura.
Se o seu plano define uma cota de e-mails agendados para o período de faturamento, cada envio agendado consome uma unidade dessa cota. Exceder essa cota é rejeitado com um 422 (E10003).
Agende conteúdo inline ou um modelo
Use scheduled_at com conteúdo inline ou um modelo salvo, montado como em um envio com modelo imediato. Ao aceitar a solicitação, salvamos a versão publicada, o idioma selecionado, os parâmetros fornecidos por quem faz a chamada, os valores dos contatos e os links de cancelamento de assinatura, e usamos esses valores salvos no horário agendado. Edições e exclusões de contatos e mudanças de fallback não alteram a mensagem aceita. Publicar uma versão mais recente não altera a seleção. Se o modelo for excluído antes do horário agendado, a mensagem será rejeitada sem ser enviada.
Uma mensagem da categoria marketing recebe um link de cancelamento de assinatura como um pequeno rodapé no final do corpo. Para posicionar o link você mesmo, coloque {{ bird.unsubscribe_url }} em cada corpo fornecido ou, em um envio com modelo, nos corpos do modelo.
Um item de batch aceita scheduled_at nos mesmos termos, então um batch pode misturar mensagens agendadas e imediatas. Cada item agendado consome sua própria unidade da cota, e o batch inteiro é rejeitado se o horário de qualquer item estiver fora do intervalo permitido. Cada item agendado traz seu próprio scheduled_at na resposta do batch, e um item de envio imediato não tem a chave scheduled_at; a referência do batch mostra ambos em uma mesma resposta.
As mensagens canceladas mantêm os valores de destinatário aceitos para o histórico. Se o snapshot salvo ficar indisponível, o status e o assunto representativo continuam legíveis, os assuntos por destinatário são omitidos e o conteúdo não pode ser recuperado a partir dos contatos atuais.
Tamanho da mensagem
Um envio agendado tem o mesmo limite de 20 MB por mensagem de um envio imediato e retorna o mesmo 413 (E04002) quando o ultrapassa. Os corpos HTML e de texto e o conteúdo dos arquivos de anexos e imagens inline contam para esse limite, e não para o limite de agendamento descrito abaixo.
O restante de uma solicitação agendada compartilha um limite de 31 KB. Isso inclui os endereços e nomes dos destinatários, reply_to, subject, headers personalizados, tags, metadata, parameters ou template.parameters, além de algumas centenas de bytes por anexo para o nome do arquivo e seus detalhes. A maioria dos envios fica bem abaixo desse limite; 150 destinatários com nomes e endereços típicos ocupam cerca de 25 KB. Em um envio com modelo personalizado com dados de contato, cada cópia em Cc e Bcc conta como mais um destinatário, mas os valores dos contatos e os links de cancelamento de assinatura não contam. Uma solicitação acima do limite retorna 422 com param definido como scheduled_at. Envie para menos destinatários por mensagem, reduza os cabeçalhos ou parâmetros, ou envie a mensagem imediatamente.
Os valores dos contatos são armazenados quando aceitamos o agendamento. Se isso falhar, o API retorna um erro que permite tentar novamente e não agenda a mensagem. Os corpos e anexos ainda podem estar sendo armazenados após o 202. Se esse armazenamento continuar falhando, a mensagem não é enviada e aparece como rejected quando você a consulta pelo ID. Nenhum webhook informa isso; portanto, consulte a mensagem pelo ID se precisar confirmar que ela foi enviada e envie-a novamente se ela tiver sido rejeitada.
Escolhendo o horário de envio
scheduled_at é um timestamp absoluto RFC 3339. Duas regras o governam:
- 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
ZUTC (2027-01-15T09:00:00Z) ou um offset explícito (2026-07-30T09:00:00-04:00, o mesmo instante que13: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.
Expressões relativas como "in 2 hours" não são aceitas. Envie um timestamp resolvido.
Listando mensagens agendadas
Filtre a lista de mensagens por status para ver as mensagens que já apareceram e ainda aguardam o envio. Um agendamento recém-aceito pode não aparecer enquanto o conteúdo é carregado ou as leituras são atualizadas:
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 scheduledcurl "https://us1.platform.bird.com/v1/email/messages?status=scheduled" \
-H "Authorization: Bearer bk_us1_..."status=canceled lista as que você cancelou antes do envio. Quando uma mensagem agendada dispara, ela entra no pipeline e aparece com os status de entrega, igual a qualquer outro envio. O log de e-mails do dashboard oferece os mesmos filtros Scheduled e Canceled.
Cancelando um envio agendado
Cancele uma mensagem a qualquer momento antes de ela começar a ser enviada com POST /v1/email/messages/{message_id}/cancel:
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> --yescurl -X POST "https://{region}.platform.bird.com/v1/email/messages/{message_id}/cancel" \
-H "Authorization: Bearer $TOKEN"Um cancelamento bem-sucedido retorna 204 No Content. O status da mensagem passa a ser canceled, ela nunca é enviada, e um webhook email.canceled dispara. Quatro coisas importantes:
-
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
409pelo mesmo motivo. -
Você pode cancelar enquanto o conteúdo ainda está sendo carregado. Um envio agendado com anexos ou um corpo de mensagem grande pode ainda estar armazenando conteúdo após a resposta
202. Um cancelamento bem-sucedido mantém o envio cancelado, mesmo que o carregamento termine mais tarde. -
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 e sua carteira não são afetadas, porque um envio só é contabilizado e cobrado quando a mensagem é realmente enviada.
-
Você pode tentar novamente o cancelamento com segurança usando um
Idempotency-Key, como qualquer outra escrita.
Para mover um envio agendado para outro horário, cancele-o e envie uma nova solicitação com o novo scheduled_at. Você recebe um novo ID em_.
O que acontece no horário de envio
O agendamento muda apenas quando a mensagem é liberada. Sua construção e governança permanecem as mesmas. Anexos, categoria, tags e metadados se comportam exatamente como em um envio imediato e são ecoados nos eventos de webhook da mesma forma. Cinco verificações se dividem entre os dois momentos:
- 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
fromnão estiver mais verificado quando o horário agendado chegar, a mensagem não é enviada. Seus destinatários retornam comorejectedcom um motivo, em vez de receberem e-mail de um domínio não verificado. Mantenha o domínio verificado durante toda a janela. - Seu envio é contabilizado e cobrado no horário de envio. O agendamento não altera sua cota de envio nem sua carteira. Quando a mensagem dispara, ela é contabilizada na cota do plano Email Free ou, em um plano Email pago, cobrada da sua carteira. Se a cota estiver esgotada, ou se a carteira não tiver mais saldo nem crédito, 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.
- Um modelo salvo precisa continuar existindo no horário de envio. Se você excluir o modelo depois de agendar, a mensagem não é enviada. Seus destinatários retornam como
rejectedcomgeneration_failure.
Erros
| Status | Código | Quando |
|---|---|---|
422 | E10003 | A cota de e-mails agendados da sua organização para o período de faturamento foi esgotada |
422 | scheduled_at está a menos de 30 segundos ou a mais de 30 dias | |
422 | Os destinatários, cabeçalhos, parâmetros e metadados ultrapassam o limite de agendamento de 31 KB | |
413 | E04002 | A mensagem gerada ultrapassa 20 MB, o mesmo limite de um envio imediato |
409 | E10005 | A mensagem não pode mais ser cancelada: já começou a ser enviada, já foi enviada ou já foi cancelada |
404 | A leitura da mensagem ainda não reflete a aceitação, ou não existe mensagem com esse ID neste espaço de trabalho |
Webhooks
Dois eventos são específicos do agendamento, além dos eventos de entrega habituais:
email.scheduledinforma sobre uma mensagem que aguarda o horário futuro definido emscheduled_at. Nos envios com modelo, a versão selecionada é carregada novamente e seu conteúdo é preparado no momento do envio. Esse evento pode chegar antes que esse trabalho seja concluído.email.canceleddispara quando uma mensagem agendada é cancelada antes do envio.
Quando a mensagem dispara, a cadeia normal de email.accepted segue sem alterações.
Os eventos de agendamento são publicados de forma assíncrona. Uma mensagem pode sair do status agendado antes que email.scheduled seja publicado. Receber um webhook não significa que os endpoints de leitura já mostrem esse estado.
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: novas tentativas 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
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.