# 创建带附件的推送通知 (POST) (Paid)

发送带图片附件的推送通知。

> **Warning: 付费功能**
>
> 此接口仅适用于付费套餐。

## 端点

```
POST https://api.pocketalert.app/v1/messages
```

## 身份验证

> **Info: 必填**
>
> 在请求中添加以下请求头之一：
> - `Token: <your-api-key>` — 在 [API 密钥](https://pocketalert.app/account/apikeys) 页面获取
> - `Authorization: Bearer <jwt-token>` — 来自 [登录](https://info.pocketalert.app/api/user/login.md)

## 请求

### 请求头

| 请求头 | 必填 | 说明 |
|--------|:--------:|-------------|
| `Content-Type` | ✅ | `multipart/form-data` |
| `Token` | ✅ | 你的 API 密钥 |

### 请求体参数（multipart/form-data）

| 参数 | 类型 | 必填 | 说明 |
|-----------|------|:--------:|-------------|
| `title` | string | ✅ | 通知标题 |
| `message` | string | ✅ | 通知正文 |
| `application_id` | string | ❌ | 应用 TID |
| `device_id` | string | ❌ | 设备 TID（留空则发送给所有设备） |
| `image` | file | ❌ | 图片附件（`.png`、`.jpg`、`.jpeg`、`.gif`） |

### 请求示例

**cURL**

```bash
curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: your-api-key" \
  -F "title=Screenshot Alert" \
  -F "message=New screenshot captured" \
  -F "image=@/path/to/screenshot.png"
```

**JavaScript**

```javascript
const formData = new FormData();
formData.append('title', 'Screenshot Alert');
formData.append('message', 'New screenshot captured');
formData.append('image', fileInput.files[0]);

const response = await fetch('https://api.pocketalert.app/v1/messages', {
  method: 'POST',
  headers: { 'Token': 'your-api-key' },
  body: formData
});
```

**Python**

```python
import requests

with open('screenshot.png', 'rb') as f:
    response = requests.post(
        'https://api.pocketalert.app/v1/messages',
        headers={'Token': 'your-api-key'},
        data={
            'title': 'Screenshot Alert',
            'message': 'New screenshot captured'
        },
        files={'image': f}
    )
print(response.json())
```

**PHP**

```php
$response = Http::withHeaders([
    'Token' => 'your-api-key',
])->attach(
    'image', file_get_contents('/path/to/screenshot.png'), 'screenshot.png'
)->post('https://api.pocketalert.app/v1/messages', [
    'title' => 'Screenshot Alert',
    'message' => 'New screenshot captured',
]);

return $response->json();
```

## 响应

### 成功响应

> **Tip: 201 Created**
>
> 带附件的消息创建成功

| 字段 | 类型 | 说明 |
|-------|------|-------------|
| `tid` | string | 消息唯一标识符 |
| `title` | string | 消息标题 |
| `message` | string | 消息正文 |
| `attachment` | object | 附件详情 |
| `attachment.tid` | string | 附件标识符 |
| `attachment.file_name` | string | 存储的文件名 |
| `attachment.content_type` | string | MIME 类型 |
| `attachment.file_size` | integer | 文件大小（字节） |

```json
{
  "tid": "zvtfxzk55fpqugz7ueslmse2a",
  "title": "Screenshot Alert",
  "message": "New screenshot captured",
  "application": "Monitoring",
  "device": "iPhone",
  "created_at": "04.01.2025 09:12:08",
  "attachment": {
    "tid": "i6k4b8un79otbcbdkmavmf4ha",
    "file_name": "5bd64bb3b76df1be1fc7f41eeb5078ca.jpg",
    "content_type": "image/jpeg",
    "file_size": 247421
  }
}
```

### 错误响应

| 状态码 | 说明 |
|:------:|-------------|
| `401` | 未授权 — 令牌无效或缺失 |
| `403` | 禁止访问 — 该功能需要付费套餐 |
| `400` | 请求错误 — 缺少 `title` 或 `message`，或文件格式不受支持 |
| `404` | 未找到 — `application_id` 或 `device_id` 不存在 |
| `429` | 已达到每日上限 — 不会存储或上传任何内容。参见[每日消息上限](https://info.pocketalert.app/features/daily-limits.md)。 |
