# Envío programado

Envía un mensaje ahora y haz que llegue más tarde. Añade `send_at` o `delay` a cualquier solicitud de [Create Message](https://info.pocketalert.app/api/messages/create.md) y Pocket Alert lo guarda cifrado hasta la hora de envío y después lo envía como una notificación push normal.

Sin tarea cron en tu lado, sin worker de cola, sin proceso que tenga que seguir activo hasta el martes.

## Dos formas de indicar cuándo

| Parámetro | Acepta | Ejemplos |
|-----------|--------|----------|
| `send_at` | RFC3339, marca de tiempo Unix o `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Duración estilo Go o solo segundos | `30m`, `2h`, `90s`, `3600` |

Envía uno u otro: si envías los dos, la respuesta es `400`.

Un `send_at` sin desfase horario se interpreta en **la zona horaria de tu cuenta**, así que `2026-08-15 09:00` significa las nueve de la mañana donde estés, no en UTC. Configúrala en la [configuración de la cuenta](https://pocketalert.app/account).

## Programar un mensaje

**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'
    }
)
```

Un mensaje programado devuelve `201` con `"scheduled": true` en lugar de un mensaje entregado:

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

Guarda el `tid`: con él cancelas el mensaje.

## Listar mensajes programados (GET)

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

Devuelve los mensajes pendientes por defecto, del más próximo al más lejano.

| Parámetro de consulta | Valores | Descripción |
|-----------------------|---------|-------------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Filtra por estado. Por defecto, `pending`. |

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

Cada elemento incluye `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at` y `actions` cuando el mensaje tiene botones.

## Cancelar (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"
```

| Estado | Significado |
|:------:|-------------|
| `200` | Cancelado. Cualquier adjunto se elimina con él. |
| `404` | No hay ningún mensaje programado con ese `tid` en tu cuenta |
| `409` | Ya enviado, ya en envío o ya cancelado |

La cancelación compite con el despachador de forma segura: si el envío ya ha comenzado, recibes `409` en lugar de un mensaje cancelado a medias.

## Reglas que conviene conocer

**El horizonte es de 30 días.** Lo que esté más lejos se rechaza.

**Las horas pasadas devuelven `400`**, con una tolerancia de 60 segundos por desfase del reloj. Dentro de esa ventana, el mensaje se envía inmediatamente.

**El nivel y el plan se resuelven al programar, no al entregar.** Un mensaje programado como `critical` con un plan de pago llega como `critical` aunque el plan caduque entre medias. Un envío programado es una promesa.

**El límite diario se cuenta al programar.** Un mensaje programado cuenta para el [límite diario de mensajes](https://info.pocketalert.app/features/daily-limits.md) del día en que lo programas, no del día en que se entrega, y el límite nunca bloquea la entrega. Si superas el límite, la propia solicitud de programación devuelve `429`. Cancelar no devuelve la cuota.

**Los adjuntos se suben al programar** y se vinculan al mensaje en el momento de la entrega. Al cancelar, se elimina el archivo guardado.

**Los mensajes atrasados se entregan tarde, no se descartan.** Si el servicio se reinicia después de una hora de entrega, el mensaje sale en el siguiente ciclo en lugar de desaparecer.

**El contenido se cifra en reposo** con tu clave personal desde el momento en que lo programas, igual que los mensajes normales.

> **Warning: Función de pago**
>
> El envío programado está disponible en los planes de pago. Una solicitud con `send_at` o `delay` en el plan gratuito devuelve `403`: nada se descarta en silencio.

## Relacionado

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — referencia completa de la solicitud
- [Niveles de prioridad](https://info.pocketalert.app/features/priority-levels.md) — cómo se comporta la alerta entregada
- [Botones de acción](https://info.pocketalert.app/features/action-buttons.md) — los mensajes programados conservan sus botones
- [Límites diarios de mensajes](https://info.pocketalert.app/features/daily-limits.md) — cómo se cuentan los mensajes programados
