# Envio agendado

Envie uma mensagem agora e faça ela chegar depois. Adicione `send_at` ou `delay` a qualquer requisição de [Create Message](https://info.pocketalert.app/api/messages/create.md) e o Pocket Alert armazena a mensagem criptografada até o horário de envio, e então a entrega como uma notificação push normal.

Sem tarefa cron do seu lado, sem worker de fila, sem processo que precise ficar de pé até terça-feira.

## Duas formas de definir quando

| Parâmetro | Aceita | Exemplos |
|-----------|--------|----------|
| `send_at` | RFC3339, timestamp Unix ou `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Duração no estilo Go ou apenas segundos | `30m`, `2h`, `90s`, `3600` |

Envie um ou outro. Enviar os dois retorna `400`.

Um `send_at` sem deslocamento de fuso horário é lido no **fuso horário da sua conta**, então `2026-08-15 09:00` significa nove da manhã onde você está, e não em UTC. Defina em [configurações da conta](https://pocketalert.app/account).

## Agendando uma mensagem

**cURL — absolute time**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Certificate expires tomorrow",
    "message": "api.example.com — renew before 09:00 UTC",
    "send_at": "2026-08-15T09:00:00Z",
    "level": "high"
  }'
```

**cURL — relative delay**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Check the migration",
    "message": "Started at 14:02 — verify row counts",
    "delay": "2h"
  }'
```

**JavaScript**

```javascript
await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Check the migration',
    message: 'Started at 14:02 — verify row counts',
    delay: '2h'
  })
});
```

**Python**

```python
import requests

requests.post(
    'https://api.pocketalert.app/v1/messages',
    headers={'Token': 'your-api-key'},
    json={
        'title': 'Check the migration',
        'message': 'Started at 14:02 — verify row counts',
        'delay': '2h'
    }
)
```

Uma mensagem agendada retorna `201` com `"scheduled": true` em vez de uma mensagem entregue:

```json
{
  "tid": "n8k2vq7pxr4m",
  "scheduled": true,
  "status": "pending",
  "title": "Check the migration",
  "deliver_at": "09.08.2026 16:02:00",
  "deliver_at_utc": "2026-08-09T13:02:00Z",
  "tz": "Europe/Berlin"
}
```

Guarde o `tid`. É com ele que você cancela.

## Listando mensagens agendadas (GET)

```
GET https://api.pocketalert.app/v1/messages/scheduled
```

Retorna as mensagens pendentes por padrão, da mais próxima para a mais distante.

| Parâmetro de consulta | Valores | Descrição |
|-----------------------|---------|-----------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Filtra por estado. O padrão é `pending`. |

```bash
curl -X GET "https://api.pocketalert.app/v1/messages/scheduled?status=all" \
  -H "Token: your-api-key"
```

Cada item traz `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at` e `actions` quando a mensagem tem botões.

## Cancelando (DELETE)

```
DELETE https://api.pocketalert.app/v1/messages/scheduled/{tid}
```

```bash
curl -X DELETE "https://api.pocketalert.app/v1/messages/scheduled/n8k2vq7pxr4m" \
  -H "Token: your-api-key"
```

| Status | Significado |
|:------:|-------------|
| `200` | Cancelada. Qualquer anexo é excluído junto. |
| `404` | Não há mensagem agendada com esse `tid` na sua conta |
| `409` | Já enviada, já em envio ou já cancelada |

O cancelamento é seguro em relação ao despachante: se a entrega já começou, você recebe `409` em vez de uma mensagem cancelada pela metade.

## Regras que vale conhecer

**O limite de agendamento é de 30 dias.** Qualquer data além disso é rejeitada.

**Horários passados retornam `400`**, com tolerância de 60 segundos para diferença de relógio. Dentro dessa janela, a mensagem é simplesmente enviada imediatamente.

**Nível e plano são definidos no momento do agendamento, não no momento da entrega.** Uma mensagem agendada como `critical` em um plano pago continua chegando como `critical`, mesmo que o plano expire no meio do caminho. Um agendamento é uma promessa.

**O limite diário é contabilizado no momento do agendamento.** Uma mensagem agendada conta para o [limite diário de mensagens](https://info.pocketalert.app/features/daily-limits.md) do dia em que você a agenda, e não do dia em que é entregue. A entrega nunca é bloqueada pelo limite. Acima do limite, a própria requisição de agendamento retorna `429`. Cancelar não devolve a cota.

**Anexos são enviados no momento do agendamento** e vinculados à mensagem na entrega. Ao cancelar, o arquivo armazenado é removido.

**Mensagens atrasadas são entregues com atraso, não descartadas.** Se o serviço reiniciar depois de um horário de entrega, a mensagem sai no próximo ciclo em vez de desaparecer.

**O conteúdo é criptografado em repouso** com a sua chave pessoal desde o momento em que você agenda, da mesma forma que as mensagens comuns.

> **Warning: Recurso pago**
>
> O envio agendado está disponível nos planos pagos. Uma requisição no plano gratuito com `send_at` ou `delay` retorna `403`. Nada é descartado silenciosamente.

## Relacionados

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — referência completa da requisição
- [Níveis de prioridade](https://info.pocketalert.app/features/priority-levels.md) — como o alerta entregue se comporta
- [Botões de ação](https://info.pocketalert.app/features/action-buttons.md) — mensagens agendadas mantêm seus botões
- [Limites diários de mensagens](https://info.pocketalert.app/features/daily-limits.md) — como as mensagens agendadas são contadas
