# Geplanter Versand

Jetzt senden, später ankommen lassen. Füge `send_at` oder `delay` zu jeder [Create Message](https://info.pocketalert.app/api/messages/create.md)-Anfrage hinzu, und Pocket Alert speichert die Nachricht verschlüsselt bis zur Zustellzeit und verschickt sie dann als ganz normale Push-Benachrichtigung.

Kein Cronjob auf deiner Seite, kein Queue-Worker, kein Prozess, der bis Dienstag am Leben bleiben muss.

## Zwei Wege, den Zeitpunkt anzugeben

| Parameter | Akzeptiert | Beispiele |
|-----------|---------|----------|
| `send_at` | RFC3339, Unix-Timestamp oder `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`, `1786867200`, `2026-08-15 09:00` |
| `delay` | Go-Dauer oder reine Sekunden | `30m`, `2h`, `90s`, `3600` |

Verwende nur eins von beiden — wenn du beide angibst, kommt `400` zurück.

Ein `send_at` ohne Zeitzonen-Offset wird in **deiner Kontozeitzone** gelesen, `2026-08-15 09:00` bedeutet also neun Uhr morgens da, wo du bist, und nicht in UTC. Stelle sie unter [Kontoeinstellungen](https://pocketalert.app/account) ein.

## Eine Nachricht planen

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

Eine geplante Nachricht gibt `201` mit `"scheduled": true` zurück, statt einer zugestellten Nachricht:

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

Bewahre die `tid` auf — damit brichst du die Nachricht ab.

## Geplante Nachrichten auflisten (GET)

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

Gibt standardmäßig ausstehende Nachrichten zurück, die nächste zuerst.

| Query-Parameter | Werte | Beschreibung |
|-----------------|--------|-------------|
| `status` | `pending`, `sending`, `sent`, `canceled`, `failed`, `all` | Nach Status filtern. Standard ist `pending`. |

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

Jeder Eintrag enthält `tid`, `title`, `message`, `priority`, `status`, `deliver_at`, `deliver_at_utc`, `tz`, `application`, `device`, `created_at` und `actions`, wenn die Nachricht Buttons hat.

## Abbrechen (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 | Bedeutung |
|:------:|---------|
| `200` | Abgebrochen. Ein eventueller Anhang wird mit gelöscht. |
| `404` | Keine geplante Nachricht mit dieser `tid` in deinem Konto |
| `409` | Bereits gesendet, gerade im Versand oder bereits abgebrochen |

Das Abbrechen ist sicher gegenüber dem Dispatcher: Hat die Zustellung bereits begonnen, bekommst du `409`, statt einer halb abgebrochenen Nachricht.

## Regeln, die man kennen sollte

**Der Planungshorizont beträgt 30 Tage.** Alles, was weiter in der Zukunft liegt, wird abgelehnt.

**Vergangene Zeitpunkte liefern `400`**, mit 60 Sekunden Toleranz für Uhrenabweichungen. Innerhalb dieses Fensters wird die Nachricht einfach sofort gesendet.

**Stufe und Tarif werden beim Planen festgelegt, nicht bei der Zustellung.** Eine als `critical` geplante Nachricht in einem bezahlten Tarif kommt weiterhin als `critical` an, auch wenn der Tarif zwischendurch ausläuft. Eine Planung ist ein Versprechen.

**Das Tageslimit wird beim Planen angerechnet.** Eine geplante Nachricht zählt zum [Tageslimit für Nachrichten](https://info.pocketalert.app/features/daily-limits.md) des Tages, an dem du sie planst, nicht des Tages der Zustellung. Die Zustellung wird vom Limit nie blockiert. Bei Überschreitung gibt die Planungsanfrage selbst `429` zurück. Ein Abbruch gibt das Kontingent nicht zurück.

**Anhänge werden zum Zeitpunkt der Planung hochgeladen** und bei der Zustellung mit der Nachricht verknüpft. Beim Abbrechen wird die gespeicherte Datei entfernt.

**Überfällige Nachrichten werden verspätet zugestellt, nicht verworfen.** Startet der Dienst nach einem Zustellzeitpunkt neu, geht die Nachricht beim nächsten Durchlauf raus, statt zu verschwinden.

**Inhalte sind ab dem Moment der Planung im Ruhezustand mit deinem persönlichen Schlüssel verschlüsselt**, genau wie bei regulären Nachrichten.

> **Warning: Bezahlte Funktion**
>
> Geplanter Versand ist in bezahlten Tarifen verfügbar. Eine Anfrage im kostenlosen Tarif mit `send_at` oder `delay` liefert `403` — nichts wird stillschweigend verworfen.

## Verwandte Seiten

- [Create Message](https://info.pocketalert.app/api/messages/create.md) — vollständige Anfragereferenz
- [Prioritätsstufen](https://info.pocketalert.app/features/priority-levels.md) — wie sich die zugestellte Meldung verhält
- [Aktionsbuttons](https://info.pocketalert.app/features/action-buttons.md) — geplante Nachrichten behalten ihre Buttons
- [Tageslimits für Nachrichten](https://info.pocketalert.app/features/daily-limits.md) — wie geplante Nachrichten gezählt werden
