# 예약 발송

지금 메시지를 보내고, 나중에 도착하게 하세요. [메시지 생성](https://info.pocketalert.app/api/messages/create.md) 요청에 `send_at` 또는 `delay`를 추가하면 Pocket Alert가 발송 시각까지 메시지를 암호화된 상태로 보관했다가 일반 푸시 알림처럼 보내 드립니다.

직접 크론 작업을 설정할 필요도, 큐 워커를 운영할 필요도, 화요일까지 프로세스를 살려 둘 필요도 없습니다.

## 발송 시각을 지정하는 두 가지 방법

| 매개변수 | 허용 형식 | 예시 |
|-----------|---------|----------|
| `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`로 도착합니다. 예약은 약속입니다.

**일일 한도는 예약할 때 차감됩니다.** 예약된 메시지는 발송된 날이 아니라 예약한 날의 [일일 메시지 한도](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) — 예약된 메시지도 버튼을 그대로 유지합니다
- [일일 메시지 한도](https://info.pocketalert.app/features/daily-limits.md) — 예약 메시지가 집계되는 방식
