TempMail Developer API

Tích hợp email tạm thời vào ứng dụng của bạn trong vài phút. Tạo địa chỉ, đọc email, lấy OTP — tất cả qua REST API đơn giản.

🔑
API Key
Mọi request cần header Authorization: Bearer <key>
📦
Base URL
https://webmail.loveyuna.today
⚡
Rate Limit
200 requests / giờ per API key

Xác thực

Tất cả endpoint /v1/* yêu cầu API key trong header:

HTTP Header
Authorization: Bearer tm_your_api_key_here

Để lấy API key, vào ứng dụng TempMail → nút API trên sidebar.

Lỗi & Mã lỗi

Mọi response lỗi có format:

JSON
{
  "ok": false,
  "error": "Mô tả lỗi",
  "code": "ERROR_CODE"
}
HTTP Code Mô tả
401 UNAUTHORIZED Thiếu Authorization header
401 INVALID_KEY API key không hợp lệ hoặc đã bị xóa
400 INVALID_ADDRESS Địa chỉ email không hợp lệ
403 FORBIDDEN Email không thuộc địa chỉ yêu cầu
404 NOT_FOUND Email không tồn tại
429 RATE_LIMITED Vượt quá 200 req/giờ
500 INTERNAL Lỗi server

Rate Limit

Mỗi API key được phép 200 requests/giờ. Thông tin rate limit trả về trong header mỗi response:

Response Headers
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 187
X-RateLimit-Reset: 1746363600

Developer Endpoints

Tất cả cần Authorization: Bearer <key>

GET /v1/me

Trả về thông tin API key hiện tại và rate limit.

cURL 
curl -H "Authorization: Bearer tm_your_key" \
     https://webmail.loveyuna.today/v1/me
Response 200
{
  "ok": true,
  "data": {
    "key": "tm_a3f9b2c1...",
    "label": "My App",
    "createdAt": 1746300000000,
    "requestCount": 13,
    "rateLimit": {
      "limit": 200,
      "remaining": 187,
      "resetAt": 1746363600
    }
  }
}
GET /v1/address

Tạo một địa chỉ email tạm thời mới.

Query Parameters
Param Type Mặc định Mô tả
ttl integer 3600 Thời gian sống (giây): 600, 1800, 3600, 21600, 86400
cURL 
curl -H "Authorization: Bearer tm_your_key" \
     "https://webmail.loveyuna.today/v1/address?ttl=1800"
Response 200
{
  "ok": true,
  "data": {
    "address": "ab3f9c@webmail.loveyuna.today",
    "ttl": 1800,
    "domain": "webmail.loveyuna.today",
    "expiresAt": 1746301800
  }
}
GET /v1/inbox/:address

Lấy danh sách email trong inbox của địa chỉ. Tự động làm mới TTL.

cURL 
curl -H "Authorization: Bearer tm_your_key" \
     https://webmail.loveyuna.today/v1/inbox/ab3f9c@webmail.loveyuna.today
Response 200
{
  "ok": true,
  "data": {
    "address": "ab3f9c@webmail.loveyuna.today",
    "count": 1,
    "emails": [
      {
        "id": "uuid-...",
        "from": "noreply@service.com",
        "subject": "Mã xác nhận của bạn",
        "date": "2025-05-04T10:00:00Z",
        "receivedAt": 1746300000000,
        "hasHtml": true,
        "otp": "382910",
        "attachments": []
      }
    ]
  }
}
GET /v1/email/:id

Lấy nội dung đầy đủ của email (HTML, text, attachments).

Query Parameters
Param Bắt buộc Mô tả
address ✓ Địa chỉ nhận email (để xác minh ownership)
cURL 
curl -H "Authorization: Bearer tm_your_key" \
     "https://webmail.loveyuna.today/v1/email/uuid?address=ab3f9c@webmail.loveyuna.today"
Response 200
{
  "ok": true,
  "data": {
    "email": {
      "id": "uuid-...",
      "from": "noreply@service.com",
      "to": "ab3f9c@webmail.loveyuna.today",
      "subject": "Mã xác nhận",
      "date": "2025-05-04T10:00:00Z",
      "receivedAt": 1746300000000,
      "text": "Mã của bạn là: 382910",
      "html": "<p>Mã của bạn là: <b>382910</b></p>",
      "otp": "382910",
      "attachments": []
    }
  }
}
DELETE /v1/email/:id

Xóa email khỏi inbox.

cURL 
curl -X DELETE \
     -H "Authorization: Bearer tm_your_key" \
     "https://webmail.loveyuna.today/v1/email/uuid?address=ab3f9c@webmail.loveyuna.today"
Response 200
{ "ok": true, "data": { "deleted": true, "id": "uuid-..." } }

Key Management

Không cần xác thực — dùng từ trình duyệt

POST /api/keys

Tạo API key mới. Key được lưu trong Redis.

cURL
curl -X POST https://webmail.loveyuna.today/api/keys \
     -H "Content-Type: application/json" \
     -d '{"label": "My App"}'
Response 201
{ "key": "tm_a3f9b2c1...", "label": "My App", "createdAt": 1746300000000 }
GET /api/keys/:key

Lấy thông tin và usage của một API key.

Response 200
{ "key": "tm_...", "label": "My App", "createdAt": 1746300000000, "requestCount": 42 }
DELETE /api/keys/:key

Thu hồi và xóa vĩnh viễn API key. Mọi request dùng key này sau đó sẽ nhận 401.

Response 200
{ "deleted": true }