# 予約送信

今すぐメッセージを作成して、あとから届けることができます。任意の [メッセージ作成](https://info.pocketalert.app/api/messages/create.md) リクエストに `send_at` または `delay` を追加すると、Pocket Alert は配信時刻まで暗号化して保存し、その後通常のプッシュ通知として送信します。

お客様側での cron ジョブ、キューワーカー、火曜日まで動かし続けるプロセスは必要ありません。

## 配信時刻の指定方法は 2 通り

| パラメータ | 指定できる形式 | 例 |
|-----------|---------|----------|
| `send_at` | RFC3339、Unix タイムスタンプ、または `YYYY-MM-DD HH:MM` | `2026-08-15T09:00:00Z`、`1786867200`、`2026-08-15 09:00` |
| `delay` | Go 形式の期間、または秒数のみ | `30m`、`2h`、`90s`、`3600` |

どちらか一方だけを指定してください。両方を指定すると `400` が返されます。

タイムゾーンのオフセットを省略した `send_at` は **お客様のアカウントのタイムゾーン** として解釈されます。そのため `2026-08-15 09:00` は UTC ではなく、お客様の地域での午前 9 時を意味します。タイムゾーンは [アカウント設定](https://pocketalert.app/account) で設定できます。

## メッセージを予約する

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

予約されたメッセージは、配信済みメッセージの代わりに `201` と `"scheduled": true` を返します。

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

`tid` は必ず保存してください。予約の取り消しに必要になります。

## 予約済みメッセージの一覧 (GET)

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

デフォルトでは、配信待ちのメッセージを配信時刻が近い順に返します。

| クエリパラメータ | 値 | 説明 |
|-----------------|--------|-------------|
| `status` | `pending`、`sending`、`sent`、`canceled`、`failed`、`all` | 状態で絞り込みます。デフォルトは `pending` です。 |

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

各項目には `tid`、`title`、`message`、`priority`、`status`、`deliver_at`、`deliver_at_utc`、`tz`、`application`、`device`、`created_at` が含まれます。メッセージにボタンがある場合は `actions` も含まれます。

## 予約の取り消し (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"
```

| ステータス | 意味 |
|:------:|---------|
| `200` | 取り消しました。添付ファイルも一緒に削除されます。 |
| `404` | お客様のアカウントに、その `tid` の予約済みメッセージがありません |
| `409` | 送信済み、送信中、または取り消し済みです |

取り消しは配信処理と競合しても安全に扱われます。配信がすでに始まっている場合は、中途半端に取り消された状態ではなく `409` が返されます。

## 知っておくと役立つルール

**予約できるのは 30 日先までです。** それより先の時刻は拒否されます。

**過去の時刻は `400` になります。** ただしクロックのずれを考慮して 60 秒の猶予があります。この範囲内であれば、メッセージはすぐに送信されます。

**レベルとプランは配信時ではなく、予約時に確定します。** 有料プランで `critical` として予約したメッセージは、途中でプランが失効しても `critical` のまま届きます。予約は約束です。

**1 日の上限は予約時に計上されます。** 予約済みメッセージは、配信された日ではなく予約した日の [1 日のメッセージ上限](https://info.pocketalert.app/features/daily-limits.md) に含まれます。また、上限によって配信がブロックされることはありません。上限を超えている場合、予約リクエスト自体が `429` を返します。予約を取り消しても、上限の枠は戻りません。

**添付ファイルは予約時にアップロードされ**、配信時にメッセージと紐づけられます。予約を取り消すと、保存されたファイルも削除されます。

**配信時刻を過ぎたメッセージは、破棄されず遅れて配信されます。** 配信時刻を過ぎている間にサービスが再起動した場合、メッセージは消えることなく次のタイミングで送信されます。

**コンテンツは予約した時点から、通常のメッセージと同じくお客様個人の鍵で保存時に暗号化されます。**

> **Warning: 有料機能**
>
> 予約送信は有料プランでご利用いただけます。無料プランで `send_at` または `delay` を指定したリクエストは `403` を返します。黙って破棄されることはありません。

## 関連ページ

- [メッセージ作成](https://info.pocketalert.app/api/messages/create.md) — リクエストの詳細リファレンス
- [優先度レベル](https://info.pocketalert.app/features/priority-levels.md) — 配信されたアラートの動作
- [アクションボタン](https://info.pocketalert.app/features/action-buttons.md) — 予約済みメッセージもボタンを保持します
- [1 日のメッセージ上限](https://info.pocketalert.app/features/daily-limits.md) — 予約済みメッセージのカウント方法
