Base URL
https://mail.giare.pw
Tất cả API trả về Content-Type: application/json
📬 Mailbox
POST
/api/mailboxes
Public
►
Tạo hộp thư mới. Nếu hộp thư đã tồn tại, trả về thông tin hộp thư hiện tại.
| Param | Kiểu | Mô tả |
|---|---|---|
| domain | string | Tên miền (tùy chọn). Nếu bỏ trống, chọn domain ngẫu nhiên. |
| localPart | string | Phần trước @ (tùy chọn). Nếu bỏ trống, tự động random. |
Request (POST /api/mailboxes)
{
"domain": "giare.io.vn",
"localPart": "testuser"
}
Response (200 OK)
{
"address": "testuser@giare.io.vn",
"localPart": "testuser",
"domain": "giare.io.vn"
}
GET
/api/mailboxes/:address/messages
Public
►
Lấy danh sách email trong hộp thư với phân trang.
| Param | Kiểu | Mô tả |
|---|---|---|
| :address | path | Địa chỉ email đầy đủ (VD: user@domain.com) |
| page | query | Số trang (mặc định: 1) |
| limit | query | Thư/trang (mặc định: 20, tối đa: 100) |
Response (200 OK)
{
"messages": [
{
"id": "abc-123",
"from": "noreply@company.com",
"subject": "Welcome to our service",
"preview": "Nội dung email...",
"date": 1740000000000,
"hasAttachments": false
}
],
"total": 5,
"page": 1,
"pages": 1
}
GET
/api/messages/:id
Public
►
Lấy chi tiết một email cụ thể bao gồm nội dung HTML đầy đủ.
| Param | Kiểu | Mô tả |
|---|---|---|
| :id | path | ID của email |
Response (200 OK)
{
"id": "abc-123",
"from": "noreply@company.com",
"to": ["user@domain.com"],
"subject": "Tiêu đề email",
"date": 1740000000000,
"html": "<html>...</html>",
"text": "Nội dung plain text...",
"attachments": [],
"headers": {}
}
DELETE
/api/messages/:id
Public
►
Xóa một email cụ thể khỏi hộp thư.
| Param | Kiểu | Mô tả |
|---|---|---|
| :id | path | ID của email cần xóa |
Response (200 OK)
{ "ok": true }
⚠️ Error Handling
API trả về các mã HTTP tiêu chuẩn. Luôn kiểm tra status code trước khi xử lý response.
200 Success
400 Bad request
404 Not found
500 Server error
Error Response
{
"error": "Không tìm thấy hộp thư"
}
💻 Ví dụ sử dụng
Shell: Lấy email của
testuser@giare.io.vn
curl -s https://mail.giare.pw/api/mailboxes/testuser@giare.io.vn/messages | jq
Python:
import requests
res = requests.get("https://mail.giare.pw/api/mailboxes/test@giare.io.vn/messages")
print(res.json())
JavaScript:
const res = await fetch("https://mail.giare.pw/api/mailboxes/test@giare.io.vn/messages");
const data = await res.json();