Agendar e cancelar e-mails

Esta página explica como agendar um e-mail para mais tarde com a API de e-mail, como mudá-lo para outro horário e como cancelar um e-mail antes de ele sair. O cancelamento também funciona para e-mails que não foram agendados, desde que ainda não tenham sido entregues.

Agendar um e-mail

Adicione scheduled_at a uma requisição de envio. A resposta traz "status": "scheduled" e o horário normalizado em scheduled_at, e o e-mail de cada destinatário emite email.scheduled em vez de email.accepted.

scheduled_at aceita estes formatos:

Um horário igual ao atual ou no passado envia o e-mail imediatamente, com o status accepted.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z"
  }'

const email = await emailit.emails.send({
  from: 'Acme <reminders@acme.com>',
  to: 'ada@example.com',
  subject: 'Your appointment is tomorrow',
  text: 'See you at 14:00.',
  scheduled_at: '2026-10-05T09:00:00Z',
});

email = client.emails.send({
    "from": "Acme <reminders@acme.com>",
    "to": "ada@example.com",
    "subject": "Your appointment is tomorrow",
    "text": "See you at 14:00.",
    "scheduled_at": "2026-10-05T09:00:00Z",
})

$email = $emailit->emails()->send([
    'from' => 'Acme <reminders@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Your appointment is tomorrow',
    'text' => 'See you at 14:00.',
    'scheduled_at' => '2026-10-05T09:00:00Z',
]);

O Emailit prepara um e-mail agendado no momento da requisição, e não no horário de envio. O template é renderizado, os anexos por URL são baixados e os créditos são cobrados antecipadamente. Para alterar o conteúdo, cancele o e-mail e envie um novo.

Alterar o horário de envio

Use Atualizar um e-mail agendado (POST /emails/{id}) com um novo scheduled_at. Os mesmos formatos são aceitos.

• O status do e-mail deve ser scheduled.
• O horário de envio atual deve estar a mais de 3 minutos de distância.
• O novo horário de envio deve estar mais de 3 minutos no futuro.

curl https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-10-05T15:00:00Z" }'

await emailit.emails.update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', {
  scheduled_at: '2026-10-05T15:00:00Z',
});

client.emails.update("em_33VtK8mRq1xZp7LwN4cY2bHsDfa", {
    "scheduled_at": "2026-10-05T15:00:00Z",
})

$emailit->emails()->update('em_33VtK8mRq1xZp7LwN4cY2bHsDfa', [
    'scheduled_at' => '2026-10-05T15:00:00Z',
]);

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "scheduled",
  "scheduled_at": "2026-10-05T15:00:00.000Z",
  "updated_at": "2026-10-01T10:02:44.193027Z",
  "message": "Email schedule has been updated successfully"
}

Ao contrário de um novo envio, aqui um horário ilegível é rejeitado com 422 Invalid scheduled_at. Uma requisição que desrespeita a regra dos 3 minutos, ou que se refere a um e-mail que não está agendado, falha com 422 Cannot update email. Uma requisição com vários destinatários cria um e-mail por destinatário, então reagende cada ID em_ do mapa ids. Não é possível reagendar pelo painel.

Cancelar um e-mail

Você pode cancelar um e-mail de saída enquanto ele estiver com um destes status:

curl -X POST https://api.emailit.com/v2/emails/em_33VtK8mRq1xZp7LwN4cY2bHsDfa/cancel \
  -H "Authorization: Bearer $EMAILIT_API_KEY"

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "status": "canceled",
  "in_flight": false,
  "message": "Email has been canceled and removed from the send queue."
}

Quando in_flight é true, o e-mail foi cancelado, mas uma tentativa de entrega pode já estar em andamento, e a mensagem diz “The current delivery attempt may still complete; remaining retries were stopped.” Um status que não pode ser cancelado, ou um e-mail agendado a menos de 3 minutos do horário de envio, retorna 422 Cannot cancel email.

O cancelamento não reembolsa os créditos cobrados quando o e-mail foi enviado pela API.

Como o cancelamento funciona

O cancelamento retira o e-mail da fila de envio. Ele não recupera a mensagem da caixa de entrada do destinatário.

1. O Emailit verifica se o e-mail ainda pode ser cancelado.
2. Ele define o status como canceled, adiciona uma entrada “Canceled” ao histórico de entrega do e-mail e o remove da fila de envio.
3. Se um processo de entrega já tiver pegado o e-mail, ele verifica o status de novo logo antes de entregar a mensagem ao servidor do destinatário e a ignora quando vê canceled.
4. O Emailit emite email.canceled com o previous_status.

Se a mensagem já estava a caminho do servidor do destinatário, essa tentativa ainda pode ser bem-sucedida. O Emailit mantém o status canceled mesmo que a tentativa concorrente seja entregue ou dê bounce, mas o destinatário ainda pode receber a mensagem. Pense no cancelamento como “impedir que saia”, e não como “desfazer o envio”.

Status e eventos

Um e-mail agendado não emite email.accepted quando chega o horário de envio. Consulte Status de e-mail para ver a lista completa.

Veja também

• Atualizar um e-mail agendado
• Cancelar um e-mail
• Enviar um e-mail
• Status de e-mail
• Por que o meu e-mail está parado em Accepted ou Scheduled?