Test Message 1

## 認證

了解如何獲取和使用API金鑰

## 獲取API金鑰

在開始使用API之前，您需要先獲取API金鑰。您可以在個人中心頁面建立您的API金鑰。

### 使用API金鑰

在所有API請求的請求標頭中包含您的API金鑰：

[Code (bash)]
X-API-Key: YOUR_API_KEY
[/Code]

### 注意事項

- 請妥善保管您的API金鑰，不要在公開場所洩露
- API金鑰具有與您帳戶相同的權限，請謹慎使用
- 如果您的API金鑰洩露，請立即在個人中心重新產生新的金鑰

---

## 電子郵件API

建立和管理電子郵件

## 獲取可用網域清單

獲取系統中所有可用的電子郵件網域。

### 請求

[Code (bash)]
GET /api/email/domains
[/Code]

### 請求範例

[Code (bash)]
curl https://chat-tempmail.com/api/email/domains \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
domains | array | 可用的電子郵件網域清單

### 回應範例

[Code (json)]
{
  "domains": [
    "chat-tempmail.com",
    "example.com", 
    "other-domain.com"
  ]
}
[/Code]

## 建立電子郵件

建立一個新的臨時電子郵件地址。

### 請求

[Code (bash)]
POST /api/emails/generate
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
name | string | 是 | 電子郵件前綴
expiryTime | number | 是 | 有效期（毫秒）<br/>可選值：<br/>- 3600000 (1小時)<br/>- 86400000 (1天)<br/>- 259200000 (3天)<br/>- 0 (永久)
domain | string | 是 | 電子郵件網域

### 請求範例

[Code (bash)]
curl -X POST https://chat-tempmail.com/api/emails/generate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test",
    "expiryTime": 3600000,
    "domain": "chat-tempmail.com"
  }'
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
id | string | 電子郵件的唯一識別碼（UUID格式）
email | string | 建立的電子郵件地址（完整的電子郵件地址）

### 回應範例

[Code (json)]
{
  "id": "c2c4f894-c672-4d5b-a918-abca95aff1f7",
  "email": "test@chat-tempmail.com"
}
[/Code]

## 獲取電子郵件清單

獲取您帳戶下的所有電子郵件清單。

### 請求

[Code (bash)]
GET /api/emails
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
cursor | string | 否 | 分頁游標，從上一次請求的回應中獲取 nextCursor

### 請求範例

[Code (bash)]
curl https://chat-tempmail.com/api/emails \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
emails | array | 電子郵件清單（每次最多返回20條資料）
nextCursor | string | 下一頁的游標，用於獲取更多資料
total | number | 電子郵件總數

### emails 陣列中的電子郵件物件

參數名 | 類型 | 說明
-------- | ------ | ------
id | string | 電子郵件的唯一識別碼（UUID格式）
address | string | 電子郵件地址（完整的電子郵件地址）
userId | string | 電子郵件所屬的使用者ID（UUID格式）
createdAt | string | 電子郵件建立時間（ISO 8601格式）
expiresAt | string | 電子郵件過期時間（ISO 8601格式）

### 回應範例

[Code (json)]
{
  "emails": [
    {
      "id": "e4ff5c14-8a72-48c5-bd13-b5347fb944da",
      "address": "6Tg3VT@chat-tempmail.com",
      "userId": "bd08008d-e944-44b2-a0d0-67f2b528ee6d",
      "createdAt": "2025-04-21T08:30:45.084Z",
      "expiresAt": "2025-04-22T08:30:45.084Z"
    }
  ],
  "nextCursor": "fd13a8df-1465-4fbc-a612-ca7311c31ff2",
  "total": 20
}
[/Code]

## 刪除電子郵件

刪除指定的電子郵件地址。

### 請求

[Code (bash)]
DELETE /api/emails/{emailId}
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
emailId | string | 是 | 電子郵件ID（路徑參數）

### 請求範例

[Code (bash)]
curl -X DELETE "https://chat-tempmail.com/api/emails/99fadf12-6826-490a-9c6c-b0b528d4a8e0" \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
success | boolean | 是否刪除成功

### 回應範例

[Code (json)]
{
  "success": true
}
[/Code]

---

## 電子郵件API

管理電子郵件

## 獲取電子郵件清單

獲取指定電子郵件中的所有郵件清單。

### 請求

[Code (bash)]
GET /api/emails/{emailId}
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
emailId | string | 是 | 電子郵件ID（路徑參數）
cursor | string | 否 | 分頁游標（查詢參數），從上一次請求的回應中獲取 nextCursor

### 請求範例

[Code (bash)]
curl "https://chat-tempmail.com/api/emails/c2c4f894-c672-4d5b-a918-abca95aff1f7" \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
messages | array | 郵件清單（每次最多返回20條資料）
nextCursor | string | 下一頁的游標，用於獲取更多資料
total | number | 郵件總數

### messages 陣列中的郵件物件

參數名 | 類型 | 說明
-------- | ------ | ------
id | string | 郵件的唯一識別碼（UUID格式）
from_address | string | 寄件人地址
subject | string | 郵件主旨
received_at | number | 接收時間（Unix時間戳，毫秒）

### 回應範例

[Code (json)]
{
  "messages": [
    {
      "id": "fd13a8df-1465-4fbc-a612-ca7311c31ff2",
      "from_address": "sender1@example.com",
      "subject": "Test Message 1 - xJOK2h",
      "received_at": 1745224245084
    }
  ],
  "nextCursor": "eyJ0aW1lc3RhbXAiOjE3NDUxNTU4NDUwODQsImlkIjoiNjNmNzFlODYtOGE1NC00ZDQ0LTk5ZWYtN2QzNTBhMTQ4M2JiIn0=",
  "total": 50
}
[/Code]

## 獲取郵件詳情

獲取指定郵件的詳細內容。

### 請求

[Code (bash)]
GET /api/emails/{emailId}/{messageId}
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
emailId | string | 是 | 電子郵件ID（路徑參數）
messageId | string | 是 | 郵件ID（路徑參數）

### 請求範例

[Code (bash)]
curl "https://chat-tempmail.com/api/emails/99fadf12-6826-490a-9c6c-b0b528d4a8e0/fd13a8df-1465-4fbc-a612-ca7311c31ff2" \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
message | object | 郵件詳情

### message 物件欄位說明

參數名 | 類型 | 說明
-------- | ------ | ------
id | string | 郵件的唯一識別碼（UUID格式）
from_address | string | 寄件人地址
subject | string | 郵件主旨
content | string | 郵件純文字內容
html | string | 郵件HTML內容（可能為空）
received_at | number | 接收時間（Unix時間戳，毫秒）

### 回應範例

[Code (json)]
{
  "message": {
    "id": "fd13a8df-1465-4fbc-a612-ca7311c31ff2",
    "from_address": "sender1@example.com",
    "subject": "Test Message 1 - xJOK2h",
    "content": "Test Message 1\n\nThis is test message 1 content.\n\nBest regards,\nSender 1",
    "html": "<div>\n<h1>Test Message 1</h1>\n </div>",
    "received_at": 1745224245084
  }
}
[/Code]

## 刪除郵件

刪除指定的郵件。

### 請求

[Code (bash)]
DELETE /api/emails/{emailId}/{messageId}
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
emailId | string | 是 | 電子郵件ID（路徑參數）
messageId | string | 是 | 郵件ID（路徑參數）

### 請求範例

[Code (bash)]
curl -X DELETE "https://chat-tempmail.com/api/emails/76d91ae5-822a-4fdd-8701-9de038ec86d7/20e77445-b0c3-4e8b-aa29-762ea423ac15" \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
success | boolean | 是否刪除成功

### 回應範例

[Code (json)]
{
  "success": true
}
[/Code]

---

## Webhook推送

設定webhook接收郵件推送通知

## 獲取Webhook設定

獲取當前的Webhook設定資訊。

### 請求

[Code (bash)]
GET /api/webhook
[/Code]

### 請求範例

[Code (bash)]
curl https://chat-tempmail.com/api/webhook \
  -H "X-API-Key: YOUR_API_KEY"
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
url | string | Webhook URL地址（可能為空字串）
enabled | boolean | 是否啟用webhook

### 回應範例

[Code (json)]
{
  "url": "https://your-server.com/webhook",
  "enabled": true
}
[/Code]

## 設定Webhook

設定或更新Webhook設定。

### 請求

[Code (bash)]
POST /api/webhook
[/Code]

### 請求參數

參數名 | 類型 | 必填 | 說明
-------- | ------ | ------ | ------
url | string | 是 | Webhook URL地址（必須是有效的HTTP/HTTPS URL）
enabled | boolean | 是 | 是否啟用webhook

### 請求範例

[Code (bash)]
curl -X POST https://chat-tempmail.com/api/webhook \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "enabled": true
  }'
[/Code]

### 回應參數

參數名 | 類型 | 說明
-------- | ------ | ------
success | boolean | 是否設定成功

### 回應範例

[Code (json)]
{
  "success": true
}
[/Code]

## Webhook事件說明

當有新郵件到達時，系統會向您設定的URL傳送POST請求。

### 接收的資料格式

請求標頭:
- Content-Type: application/json
- X-Webhook-Event: new_message

### Webhook推送資料

參數名 | 類型 | 說明
-------- | ------ | ------
emailId | string | 接收郵件的電子郵件ID（UUID格式）
messageId | string | 新郵件的ID（UUID格式）
fromAddress | string | 寄件人地址
subject | string | 郵件主旨
content | string | 郵件純文字內容
html | string | 郵件HTML內容（可能為空）
receivedAt | string | 郵件接收時間（ISO 8601格式）
toAddress | string | 接收郵件的電子郵件地址

### 推送資料範例

[Code (json)]
{
  "emailId": "c2c4f894-c672-4d5b-a918-abca95aff1f7",
  "messageId": "fd13a8df-1465-4fbc-a612-ca7311c31ff2",
  "fromAddress": "sender@example.com",
  "subject": "測試郵件",
  "content": "郵件純文字內容",
  "html": "<div>郵件HTML內容</div>",
  "receivedAt": "2025-01-21T08:30:45.084Z",
  "toAddress": "test@chat-tempmail.com"
}
[/Code]

### 回應要求

您的伺服器應該返回2xx狀態碼表示成功接收。如果返回非2xx狀態碼，系統可能會重試傳送。

推薦的回應:

[Code (json)]
HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}
[/Code]

### 注意事項

- 請確保您的Webhook URL可以正常存取
- 建議在您的伺服器端驗證推送資料的完整性
- 系統會在郵件到達後立即傳送Webhook推送
- 如果推送失敗，系統可能會重試，請確保您的介面具有冪等性

---