TempMail — Bảng điều khiển

Tài liệu API

Dùng JWT trong header: Authorization: Bearer <token>

Khi lỗi (JSON), response thường có dạng:

{
  "error": "Message from server (localized, e.g. 400/401/404/409/500)"
}

Điểm cuối

GET/healthKhông cần JWT

Kiểm tra dịch vụ (public)

Response JSON mẫu

{
  "ok": true
}

POST/api/auth/registerKhông cần JWT

Đăng ký tài khoản

Body JSON mẫu

{
  "email": "[email protected]",
  "password": "matkhau_toi_thieu_8_ky_tu"
}

Response JSON mẫu

HTTP 201
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "usr_01ABCDEF",
    "email": "[email protected]",
    "plan": "free"
  },
  "domainCount": 0,
  "domainLimit": 5
}

POST/api/auth/loginKhông cần JWT

Đăng nhập và lấy token

Body JSON mẫu

{
  "email": "[email protected]",
  "password": "matkhau_cua_ban"
}

Response JSON mẫu

HTTP 200
{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "usr_01ABCDEF",
    "email": "[email protected]",
    "plan": "free"
  },
  "domainCount": 2,
  "domainLimit": 5
}

GET/api/meCần JWT

Thông tin tài khoản và gói hiện tại

Response JSON mẫu

{
  "user": {
    "id": "usr_01ABCDEF",
    "email": "[email protected]",
    "plan": "premium"
  },
  "plan": "premium",
  "domainCount": 3,
  "domainLimit": 50
}

POST/api/plan/redeemCần JWT

Kích hoạt gói Premium hoặc Creator bằng mã

Body JSON mẫu

{
  "code": "your-secret-code",
  "tier": "premium"
}

Response JSON mẫu

{
  "plan": "premium",
  "domainCount": 3,
  "domainLimit": 50,
  "message": "Da kich hoat goi Premium"
}

GET/api/domainsCần JWT

Lấy danh sách tên miền của người dùng

Response JSON mẫu

{
  "domains": [
    {
      "id": "dom_01ABCDEF",
      "name": "example.com",
      "status": "verified",
      "verified_at": "2025-03-19T10:00:00.000Z",
      "verification_token": "a1b2c3...",
      "created_at": "2025-03-19T09:00:00.000Z"
    },
    {
      "id": "dom_02FEDCBA",
      "name": "pending.example.com",
      "status": "pending",
      "verified_at": null,
      "verification_token": "d4e5f6...",
      "created_at": "2025-03-19T08:00:00.000Z"
    }
  ]
}

POST/api/domainsCần JWT

Thêm tên miền mới (ví dụ example.com)

Body JSON mẫu

{
  "name": "example.com"
}

Response JSON mẫu

HTTP 201
{
  "id": "dom_01ABCDEF",
  "name": "example.com",
  "status": "pending",
  "verificationToken": "a1b2c3d4e5f6...",
  "dnsGuide": {
    "mx": "route1.mx.cloudflare.net",
    "mxCloudflare": "route1.mx.cloudflare.net",
    "mxSmtp": "mail.khomail.org",
    "txt": "tempmail-verification=a1b2c3d4e5f6..."
  }
}

DELETE/api/domains/:idCần JWT

Xóa tên miền (đã hoặc chưa xác minh), xóa luôn thư và địa chỉ liên quan

Response JSON mẫu

{
  "ok": true
}

POST/api/domains/:id/verifyCần JWT

Kiểm tra MX/TXT và xác minh tên miền

Response JSON mẫu

{
  "verified": true,
  "checks": {
    "hasExpectedMx": true,
    "hasExpectedTxt": true,
    "txtRecords": [
      "tempmail-verification=a1b2c3..."
    ],
    "mxRecords": [
      "10 route1.mx.cloudflare.net."
    ]
  },
  "expected": {
    "mx": "route1.mx.cloudflare.net",
    "mxCloudflare": "route1.mx.cloudflare.net",
    "mxSmtp": "mail.khomail.org",
    "mxHosts": [
      "route1.mx.cloudflare.net",
      "mail.khomail.org"
    ],
    "txt": "tempmail-verification=a1b2c3..."
  }
}

GET/api/domains/:id/addressesCần JWT

Danh sách địa chỉ của một tên miền

Response JSON mẫu

{
  "domain": "example.com",
  "addresses": [
    {
      "id": "adr_01ABCDEF",
      "local_part": "tmpa1b2c3d4e",
      "is_active": 1,
      "created_at": "2025-03-19T11:00:00.000Z",
      "address": "[email protected]"
    }
  ]
}

POST/api/domains/:id/addresses/generateCần JWT

Tạo địa chỉ mới trên tên miền

Response JSON mẫu

{
  "id": "adr_01ABCDEF",
  "localPart": "tmpa1b2c3d4e",
  "address": "[email protected]"
}

GET/api/inboxCần JWT

Lấy danh sách thư (polling)

URL mẫu (query)

Tất cả tham số đều tùy chọn: domainId, address, since (ISO 8601).

https://tempmail-worker.mailnhanh.workers.dev/api/inbox?domainId=dom_01ABCDEF&[email protected]&since=2025-03-19T00:00:00.000Z

Response JSON mẫu

{
  "emails": [
    {
      "id": "eml_01ABCDEF",
      "sender": "[email protected]",
      "recipient": "[email protected]",
      "subject": "Xin chào",
      "created_at": "2025-03-19T12:00:00.000Z",
      "domain_name": "example.com"
    }
  ]
}

GET/api/emails/:idCần JWT

Chi tiết thư và đính kèm

Response JSON mẫu

{
  "email": {
    "id": "eml_01ABCDEF",
    "sender": "[email protected]",
    "recipient": "[email protected]",
    "subject": "Tiêu đề",
    "bodyHtml": "<p>Nội dung</p>",
    "bodyText": "Nội dung",
    "createdAt": "2025-03-19T12:00:00.000Z"
  },
  "attachments": [
    {
      "id": "att_01ABCDEF",
      "file_name": "file.pdf",
      "file_size": 102400
    }
  ]
}

GET/api/emails/:id/downloadCần JWT

Tải tệp .eml

Response mẫu (không phải JSON)

Thân response là nội dung nhị phân hoặc văn bản RFC 822, không phải object JSON.

HTTP 200
Content-Type: message/rfc822
Content-Disposition: attachment; filename="email-eml_01ABCDEF.eml"

From: [email protected]
To: [email protected]
Subject: Tiêu đề
Date: 2025-03-19T12:00:00.000Z
Content-Type: text/plain; charset=utf-8

Nội dung thư (hoặc toàn bộ .eml gốc nếu có raw_eml trong DB).

GET/api/attachments/:idCần JWT

Tải tệp đính kèm

Response mẫu (không phải JSON)

Thân response là nội dung nhị phân hoặc văn bản RFC 822, không phải object JSON.

HTTP 200
Content-Type: application/pdf   (hoặc loại MIME đã lưu trên R2)
Content-Disposition: attachment; filename="file.pdf"

<Nội dung nhị phân của tệp đính kèm>

Ví dụ gọi API

curl -X POST "https://tempmail-worker.mailnhanh.workers.dev/api/domains" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"example.com"}'

Đang tải…

{ "domains": [ { "id": "dom_01ABCDEF", "name": "example.com", "status": "verified", "verified_at": "2025-03-19T10:00:00.000Z", "verification_token": "a1b2c3...", "created_at": "2025-03-19T09:00:00.000Z" }, { "id": "dom_02FEDCBA", "name": "pending.example.com", "status": "pending", "verified_at": null, "verification_token": "d4e5f6...", "created_at": "2025-03-19T08:00:00.000Z" } ] }

HTTP 201 { "id": "dom_01ABCDEF", "name": "example.com", "status": "pending", "verificationToken": "a1b2c3d4e5f6...", "dnsGuide": { "mx": "route1.mx.cloudflare.net", "mxCloudflare": "route1.mx.cloudflare.net", "mxSmtp": "mail.khomail.org", "txt": "tempmail-verification=a1b2c3d4e5f6..." } }

{ "verified": true, "checks": { "hasExpectedMx": true, "hasExpectedTxt": true, "txtRecords": [ "tempmail-verification=a1b2c3..." ], "mxRecords": [ "10 route1.mx.cloudflare.net." ] }, "expected": { "mx": "route1.mx.cloudflare.net", "mxCloudflare": "route1.mx.cloudflare.net", "mxSmtp": "mail.khomail.org", "mxHosts": [ "route1.mx.cloudflare.net", "mail.khomail.org" ], "txt": "tempmail-verification=a1b2c3..." } }

{ "domain": "example.com", "addresses": [ { "id": "adr_01ABCDEF", "local_part": "tmpa1b2c3d4e", "is_active": 1, "created_at": "2025-03-19T11:00:00.000Z", "address": "[email protected]" } ] }

{ "emails": [ { "id": "eml_01ABCDEF", "sender": "[email protected]", "recipient": "[email protected]", "subject": "Xin chào", "created_at": "2025-03-19T12:00:00.000Z", "domain_name": "example.com" } ] }

{ "email": { "id": "eml_01ABCDEF", "sender": "[email protected]", "recipient": "[email protected]", "subject": "Tiêu đề", "bodyHtml": "<p>Nội dung</p>", "bodyText": "Nội dung", "createdAt": "2025-03-19T12:00:00.000Z" }, "attachments": [ { "id": "att_01ABCDEF", "file_name": "file.pdf", "file_size": 102400 } ] }

HTTP 200 Content-Type: message/rfc822 Content-Disposition: attachment; filename="email-eml_01ABCDEF.eml" From: [email protected] To: [email protected] Subject: Tiêu đề Date: 2025-03-19T12:00:00.000Z Content-Type: text/plain; charset=utf-8 Nội dung thư (hoặc toàn bộ .eml gốc nếu có raw_eml trong DB).