# Agendar e cancelar e-mails

> Envie um e-mail mais tarde com scheduled_at, altere o horário de envio ou cancele um e-mail agendado, aceito ou em nova tentativa pela API ou pelo painel.

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](/pt/docs/email-api/send-email/). A resposta traz `"status": "scheduled"` e o horário normalizado em `scheduled_at`, e o e-mail de cada destinatário emite [`email.scheduled`](/pt/docs/webhooks/events/email/scheduled/) em vez de `email.accepted`.

`scheduled_at` aceita estes formatos:

| Formato | Exemplo | Observações |
| --- | --- | --- |
| ISO 8601 com fuso horário | `2026-10-05T09:00:00Z`, `2026-10-05T09:00:00+02:00` | Recomendado. Inclua sempre `Z` ou um deslocamento. |
| Linguagem natural | `tomorrow at 9am`, `in 2 hours`, `next monday 10:00`, `friday 5pm` | Interpretado em UTC, então `tomorrow at 9am` significa 09:00 UTC. |

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

> **Confira o status da resposta:** Se o Emailit não conseguir ler o valor de `scheduled_at`, ele não rejeita a requisição: o e-mail é enviado na hora. Confira se a resposta tem `"status": "scheduled"` e o `scheduled_at` que você esperava. Timestamps Unix não são reconhecidos; converta-os antes para ISO 8601.

**cURL**

```bash
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"
  }'
```

**Node.js**

```javascript
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',
});
```

**Python**

```python
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",
})
```

**PHP**

```php
$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](/pt/docs/api-reference/emails/update/) (`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**

```bash
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" }'
```

**Node.js**

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

**Python**

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

**PHP**

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

```json
{
  "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:

| Status | É possível cancelar? | Observações |
| --- | --- | --- |
| `scheduled` | Sim | Somente enquanto o horário de envio estiver a mais de 3 minutos de distância. |
| `accepted` | Sim, em regime de melhor esforço | O e-mail está esperando na fila de envio ou prestes a sair dela. |
| `attempted` | Sim, em regime de melhor esforço | Uma tentativa de entrega falhou temporariamente. O cancelamento interrompe as novas tentativas restantes. |
| Qualquer outro status | Não | E-mails entregues, com bounce, com falha, rejeitados, suprimidos, retidos ou já cancelados não podem ser cancelados. |

**Painel**

  1. Acesse **Email API → Emails**.
  2. Selecione **Cancel delivery** na linha do e-mail, ou abra o e-mail e selecione **Cancel delivery** no topo da página.
  3. Confirme. Se uma tentativa de entrega já tiver começado, o painel avisa que a tentativa ainda pode ser concluída e que as novas tentativas restantes foram interrompidas.

**API**

  Chame [Cancelar um e-mail](/pt/docs/api-reference/emails/cancel/) (`POST /emails/{id}/cancel`). Funciona com chaves **Full Access** e **Sending Only**.

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

```json
{
  "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

| Momento | Status | Evento de webhook |
| --- | --- | --- |
| Requisição com um `scheduled_at` no futuro | `scheduled` | [`email.scheduled`](/pt/docs/webhooks/events/email/scheduled/) |
| Chega o horário de envio | `delivered`, `attempted`, `bounced` etc. | O evento de entrega correspondente, como [`email.delivered`](/pt/docs/webhooks/events/email/delivered/) |
| Cancelado | `canceled` | `email.canceled`, com `status` e `previous_status` |

Um e-mail agendado não emite `email.accepted` quando chega o horário de envio. Consulte [Status de e-mail](/pt/docs/logs/email-statuses/) para ver a lista completa.

## Veja também

- [Atualizar um e-mail agendado](/pt/docs/api-reference/emails/update/)
- [Cancelar um e-mail](/pt/docs/api-reference/emails/cancel/)
- [Enviar um e-mail](/pt/docs/email-api/send-email/)
- [Status de e-mail](/pt/docs/logs/email-statuses/)
- [Por que o meu e-mail está parado em Accepted ou Scheduled?](/pt/docs/kb/email-stuck-in-scheduled-or-accepted/)

---
Fonte: https://emailit.com/pt/docs/email-api/scheduling/