Danh sách kiểm tra thiết lập nhanh
- Mở trang quản lý API của bảng điều khiển và tạo khóa API cá nhân.
- Sao chép chính xác URL cơ sở API người dùng được hiển thị ở đó, ví dụ https://v1.tempmailg.com/api.
- Gửi mọi yêu cầu đến máy chủ API đó với Authorization: Bearer YOUR_USER_API_KEY và Accept: application/json.
- Theo dõi hạn ngạch yêu cầu hàng tháng của bạn từ cùng một trang bảng điều khiển và từ các tiêu đề hạn ngạch khi có sẵn trong phản hồi API của người dùng. Chỉ các yêu cầu thành công 2xx mới được tính vào hạn ngạch.
Lưu trình xác thực
- Tạo khóa API cá nhân của bạn từ trang Quản lý API trên dashboard.
- Gửi khóa dưới dạng mã thông báo Bearer trong mọi yêu cầu.
- Sử dụng URL cơ sở API người dùng chuyên dụng được hiển thị trên trang Quản lý API của bạn.
- Tạo lại khóa bất cứ lúc nào bạn muốn hủy khóa cũ và bắt đầu sử dụng một khóa mới ngay lập tức.
Tiêu đề yêu cầu
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
Tiêu đề Giới hạn Tốc độ & Hạn ngạch
Tiêu đề giới hạn tốc độ mô tả ngân sách yêu cầu được chỉ định. Tiêu đề hạn ngạch được bao gồm khi thông tin hạn ngạch có sẵn; các từ chối giới hạn phút không tính toàn bộ hạn ngạch hàng tháng của bạn.
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1729520000
X-Quota-Limit: 50000
X-Quota-Remaining: 48210
X-Quota-Used: 1790
X-Quota-Reset: 2026-11-01T00:00:00+00:00
X-RateLimit-Scope: account
Retry-After: 42 (when a timed retry is available)
X-RateLimit-Limit— Số yêu cầu tối đa cho phép mỗi phút (RPM) cho gói của bạn.X-RateLimit-Remaining— Số yêu cầu RPM còn lại trong cửa sổ phút hiện tại.X-RateLimit-Reset— Dấu thời gian Unix khi cửa sổ giới hạn tốc độ phút hiện tại được đặt lại.X-Quota-Limit— Tổng dung lượng tín dụng hàng tháng và đã mua cho tài khoản của bạn.X-Quota-Remaining— Số yêu cầu API còn lại có sẵn trong tháng hiện tại.X-Quota-Used— Tổng số yêu cầu API đã tiêu thụ trong kỳ thanh toán hiện tại.X-Quota-Reset— Dấu thời gian ISO-8601 khi hạn mức hàng tháng của bạn được đặt lại.X-RateLimit-Scope— Ngân sách được mô tả bởi các tiêu đề: account, ip, status_endpoint, hoặc mailbox.X-Mailbox-RateLimit-*— Ngân sách riêng cho việc tạo/cập nhật hộp thư. Các phản hồi thành công của hộp thư giữ RPM tài khoản trong X-RateLimit-*; một từ chối chỉ dành cho hộp thư sử dụng phạm vi hộp thư và cửa sổ thử lại riêng của nó.Retry-After— Số giây cho đến khi việc thử lại có thời gian thích hợp. Một gói bị vô hiệu hoá hoặc hạn ngạch đã cạn kiệt có thể yêu cầu thay đổi tài khoản, vì vậy tiêu đề này không phải lúc nào cũng có mặt.503 protection_unavailable— Bộ nhớ hoặc điều phối bảo vệ API tạm thời không khả dụng. Vui lòng thử lại sau; đây không phải là lỗi thanh toán hoặc ghi nợ tín dụng.
Quản lý hộp thư
Lấy các miền được phép, tạo hoặc chuyển hộp thư, chọn thời gian sống được phép, và xóa các địa chỉ sở hữu.
Liệt kê các miền được phép
Liệt kê các miền có sẵn để tạo email tạm thời. Lọc theo loại để chỉ xem các miền miễn phí, cao cấp hoặc tùy chỉnh được hỗ trợ bởi gói đăng ký của bạn.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
type
|
query | string | tùy chọn |
Bộ lọc cấp độ miền. Bỏ qua sẽ sử dụng tất cả khi quyền truy cập premium-domain được bật, nếu không thì miễn phí. Các giá trị được công nhận: free, basic, pro, premium, custom, ultimate, all
Mặc định:
Phụ thuộc vào tài khoản
|
const response = await fetch('https://v1.tempmailg.com/api/domains?type=free', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/domains?type=free', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/domains?type=free');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/domains?type=free' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"requested_type": "free",
"plan": "pro",
"plan_name": "Pro Plan",
"allowed_types": [
"free",
"basic",
"pro",
"premium",
"custom",
"ultimate",
"all"
],
"domains": [
{
"domain": "example.com",
"type": "Free",
"custom": false
}
]
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.requested_type |
string | Đã áp dụng bộ lọc miền. |
data.plan |
string | Thẻ gói hiện tại. |
data.plan_name |
string | Tên dễ đọc của gói hiện tại. |
data.allowed_types |
array<string> | Các bộ lọc miền có sẵn cho tài khoản này. Một bộ lọc đã được công nhận vẫn có thể bị cấm cho gói của bạn. |
data.domains |
array | Các miền có thể chọn sau khi lọc; một mảng trống là hợp lệ. |
data.domains[].domain |
string | Tên miền có thể chọn. |
data.domains[].type |
string | Nhãn cấp độ miền có thể đọc. |
data.domains[].custom |
boolean | Liệu đây có phải là miền tùy chỉnh. |
Tạo Hộp Thư Tạm Thời
Tạo một hộp thư tạm thời thuộc sở hữu. Bỏ qua tên người dùng và miền để tạo ngẫu nhiên, hoặc cung cấp tên người dùng tùy chỉnh được phép và một miền cho phép. Tham số provider có thể chọn tạo bí danh Gmail hoặc Outlook.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
username
|
body | string | tùy chọn |
Tên người dùng tùy chỉnh tùy chọn: 2 đến 64 ký tự ASCII bao gồm chữ cái, chữ số, dấu chấm, dấu gạch dưới hoặc dấu gạch ngang. Yêu cầu quyền kế hoạch; custom_username cũng được chấp nhận.
Mặc định:
Được tạo ngẫu nhiên
|
domain
|
body | string | tùy chọn |
Một trong các miền được phép trả về bởi GET /domains. Việc bỏ qua sẽ chọn một miền được phép ngẫu nhiên.
Mặc định:
Miền cho phép ngẫu nhiên
|
lifetime
|
body | string | tùy chọn |
các giá trị cho phép:
10m — 10 phút
1h — 1 giờ
2h — 2 giờ
1d — 1 ngày
1w — 1 Tuần
1m — 30 ngày
3m — 90 ngày
6m — 180 ngày
1y — 365 ngày
unlimited — Không giới hạn
Mặc định:
Thời gian sống mặc định của kế hoạch
|
provider
|
body | string | tùy chọn |
Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias.
Mặc định:
standard
|
pin_enabled
|
body | boolean | tùy chọn |
Bảo vệ PIN tùy chọn cho hộp thư mới, khi gói của bạn cho phép. Nó không thay đổi PIN của hộp thư đã tồn tại.
Mặc định:
false
|
pin
|
body | string | tùy chọn |
Yêu cầu khi pin_enabled là true: một PIN từ 6 đến 8 chữ số, được gửi dưới dạng chuỗi để giữ nguyên các số 0 ở đầu.
|
pin_confirmation
|
body | string | tùy chọn |
Bắt buộc khi pin_enabled là true. Phải khớp chính xác với pin.
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
username (tên người dùng tùy chỉnh nếu được cho phép bởi gói), domain (miền được phép, ví dụ example.com), lifetime (các giá trị cho phép: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). Bỏ qua thời gian sống, hoặc để trống, để sử dụng Thời gian sống Email Mặc định được cấu hình cho gói hàng tháng/năm hiện tại của bạn. Gửi một thời gian sống được phép như 1h để ghi đè lên mặc định đó. Không giới hạn chỉ được sử dụng khi được cấu hình làm mặc định của gói hoặc được yêu cầu và cho phép một cách rõ ràng. Các tham số trong phần body mailbox_lifetime và email_lifetime cũng được chấp nhận; giá trị không rỗng đầu tiên sẽ được ưu tiên theo thứ tự: lifetime, mailbox_lifetime, email_lifetime. Các giá trị không hợp lệ hoặc không được phép sẽ trả về HTTP 422 thay vì im lặng chọn giá trị mặc định.const response = await fetch('https://v1.tempmailg.com/api/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"id": 2301,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-20T02:18:11+00:00",
"expires_in_seconds": 86399.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:11+00:00",
"email_token": "encrypted-email-token"
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.id |
integer | ID hộp thư. Các ID, địa chỉ và token được tạo ra khác nhau cho mỗi hộp thư. |
data.pin_protected |
boolean | Cho biết hộp thư này có bảo vệ PIN hay không. Không trả về PIN hoặc hàm băm PIN. |
data.email |
string | Đã tạo địa chỉ hộp thư đầy đủ. |
data.domain |
string | Miền của hộp thư được tạo. |
data.provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
data.expire_at |
string|null | Ngày hết hạn hiệu lực dưới dạng dấu thời gian ISO-8601, hoặc null cho hộp thư không giới hạn. |
data.expires_in_seconds |
number|null | Giây còn lại không âm khi tính toán; có thể có giây phân số. Null có nghĩa là không giới hạn, không phải 0. |
data.mailbox_state |
string | Trạng thái hộp thư hiện tại: hoạt động, tạm dừng, đã hết hạn hoặc không hoạt động. |
data.receiving_enabled |
boolean | Liệu hộp thư này hiện có chấp nhận tin nhắn đến hay không. |
data.message_count |
integer | Số lượng tin nhắn tổng cộng đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.unread_message_count |
integer | Số lượng tin nhắn chưa đọc đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.last_message_received_at |
string|null | Thời gian nhận tin nhắn cuối cùng được biết theo định dạng ISO-8601, hoặc null khi không khả dụng. |
data.message_count_synced_at |
string|null | Thời gian đồng bộ đếm tin nhắn cuối cùng ở định dạng ISO-8601, hoặc null trước khi đồng bộ. |
data.created_at |
string|null | Thời gian tạo hộp thư theo định dạng ISO-8601. |
data.email_token |
string | Tham chiếu hộp thư được mã hóa không trong suốt. Nó không thay thế xác thực Bearer, kiểm tra quyền sở hữu hoặc ủy quyền PIN. |
data.pin_grant |
object | Có điều kiện: việc tạo hộp thư bảo vệ bằng PIN đang hoạt động trả về quyền đọc này; việc tạo bình thường không bảo vệ sẽ bỏ qua nó. |
data.pin_grant.mailbox_id |
integer | ID hộp thư mà quyền đọc có điều kiện được gắn vào. |
data.pin_grant.unlock_token |
string | Mã token đọc không trong suốt cho X-Mailbox-Unlock với cùng thông tin xác thực của chủ sở hữu. Giữ nó riêng tư và trong bộ nhớ; quyền đọc không cho phép xóa. |
data.pin_grant.scope |
string | Phạm vi được đọc cho quyền tạo có điều kiện. |
data.pin_grant.idle_timeout_seconds |
integer | Thời gian nhàn rỗi cho quyền đọc được phép, thường là 3600 giây. |
data.pin_grant.absolute_timeout_seconds |
integer | Thời gian sống tối đa của quyền đọc, thường là 86400 giây. |
data.pin_grant.expires_at |
string | Thời hạn cấp quyền đọc hiện tại ở định dạng ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Thời hạn cấp quyền đọc tuyệt đối theo định dạng ISO-8601. Các thay đổi bảo mật có thể thu hồi quyền cấp trước thời hạn. |
Cập nhật / Thay đổi Hộp thư
Tạo hoặc chọn một hộp thư tại tên người dùng và miền mới sau khi xác minh quyền sở hữu của hộp thư hiện tại. Điều này không đổi tên hộp thư cũ hoặc thay đổi thời gian tồn tại của nó tại chỗ. Khi đích khác nhau, hộp thư cũ vẫn còn trong lịch sử và có thể bị tạm dừng bởi giới hạn hộp thư hoạt động. Việc sử dụng lại đích hoạt động của bạn sẽ áp dụng lại thời gian tồn tại yêu cầu hoặc mặc định của gói.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
email
|
path | string | bắt buộc |
Địa chỉ email đầy đủ hiện tại của hộp thư sở hữu để chuyển đổi. Mã hoá URL mỗi đoạn đường dẫn; mã hoá dấu cộng thành %2B.
|
username
|
path | string | bắt buộc |
Tên người dùng mới mong muốn: 2 đến 64 ký tự chữ và số; tùy thuộc vào quyền tên người dùng tùy chỉnh.
|
domain
|
path | string | bắt buộc |
Tên miền được phép mới.
|
lifetime
|
body | string | tùy chọn |
các giá trị cho phép:
10m — 10 phút
1h — 1 giờ
2h — 2 giờ
1d — 1 ngày
1w — 1 Tuần
1m — 30 ngày
3m — 90 ngày
6m — 180 ngày
1y — 365 ngày
unlimited — Không giới hạn
Mặc định:
Thời gian sống mặc định của kế hoạch
|
pin_enabled
|
body | boolean | tùy chọn |
Bảo vệ PIN tùy chọn cho hộp thư mới, khi gói của bạn cho phép. Nó không thay đổi PIN của hộp thư đã tồn tại.
Mặc định:
false
|
pin
|
body | string | tùy chọn |
Yêu cầu khi pin_enabled là true: một PIN từ 6 đến 8 chữ số, được gửi dưới dạng chuỗi để giữ nguyên các số 0 ở đầu.
|
pin_confirmation
|
body | string | tùy chọn |
Bắt buộc khi pin_enabled là true. Phải khớp chính xác với pin.
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho các hộp thư được bảo vệ: sử dụng một unlock_token để đọc. Đầu tiên POST pin và scope=read tới URL mở khóa PIN. Giữ xác thực Bearer thông thường của bạn. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime (các giá trị cho phép: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Bỏ qua thời gian sống, hoặc để trống, để sử dụng Thời gian sống Email Mặc định được cấu hình cho gói hàng tháng/năm hiện tại của bạn. Gửi một thời gian sống được phép như 1h để ghi đè lên mặc định đó. Không giới hạn chỉ được sử dụng khi được cấu hình làm mặc định của gói hoặc được yêu cầu và cho phép một cách rõ ràng. Các tham số trong phần body mailbox_lifetime và email_lifetime cũng được chấp nhận; giá trị không rỗng đầu tiên sẽ được ưu tiên theo thứ tự: lifetime, mailbox_lifetime, email_lifetime. Các giá trị không hợp lệ hoặc không được phép sẽ trả về HTTP 422 thay vì im lặng chọn giá trị mặc định.const response = await fetch('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/emails/current@example.com/demo123/example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"id": 2302,
"pin_protected": false,
"email": "demo123@example.com",
"domain": "example.com",
"provider": "standard",
"expire_at": "2026-11-19T02:28:11+00:00",
"expires_in_seconds": 599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:11+00:00",
"email_token": "encrypted-email-token"
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.id |
integer | ID hộp thư. Các ID, địa chỉ và token được tạo ra khác nhau cho mỗi hộp thư. |
data.pin_protected |
boolean | Cho biết hộp thư này có bảo vệ PIN hay không. Không trả về PIN hoặc hàm băm PIN. |
data.email |
string | Đã tạo địa chỉ hộp thư đầy đủ. |
data.domain |
string | Miền của hộp thư được tạo. |
data.provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
data.expire_at |
string|null | Ngày hết hạn hiệu lực dưới dạng dấu thời gian ISO-8601, hoặc null cho hộp thư không giới hạn. |
data.expires_in_seconds |
number|null | Giây còn lại không âm khi tính toán; có thể có giây phân số. Null có nghĩa là không giới hạn, không phải 0. |
data.mailbox_state |
string | Trạng thái hộp thư hiện tại: hoạt động, tạm dừng, đã hết hạn hoặc không hoạt động. |
data.receiving_enabled |
boolean | Liệu hộp thư này hiện có chấp nhận tin nhắn đến hay không. |
data.message_count |
integer | Số lượng tin nhắn tổng cộng đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.unread_message_count |
integer | Số lượng tin nhắn chưa đọc đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.last_message_received_at |
string|null | Thời gian nhận tin nhắn cuối cùng được biết theo định dạng ISO-8601, hoặc null khi không khả dụng. |
data.message_count_synced_at |
string|null | Thời gian đồng bộ đếm tin nhắn cuối cùng ở định dạng ISO-8601, hoặc null trước khi đồng bộ. |
data.created_at |
string|null | Thời gian tạo hộp thư theo định dạng ISO-8601. |
data.email_token |
string | Tham chiếu hộp thư được mã hóa không trong suốt. Nó không thay thế xác thực Bearer, kiểm tra quyền sở hữu hoặc ủy quyền PIN. |
data.pin_grant |
object | Có điều kiện: việc tạo hộp thư bảo vệ bằng PIN đang hoạt động trả về quyền đọc này; việc tạo bình thường không bảo vệ sẽ bỏ qua nó. |
data.pin_grant.mailbox_id |
integer | ID hộp thư mà quyền đọc có điều kiện được gắn vào. |
data.pin_grant.unlock_token |
string | Mã token đọc không trong suốt cho X-Mailbox-Unlock với cùng thông tin xác thực của chủ sở hữu. Giữ nó riêng tư và trong bộ nhớ; quyền đọc không cho phép xóa. |
data.pin_grant.scope |
string | Phạm vi được đọc cho quyền tạo có điều kiện. |
data.pin_grant.idle_timeout_seconds |
integer | Thời gian nhàn rỗi cho quyền đọc được phép, thường là 3600 giây. |
data.pin_grant.absolute_timeout_seconds |
integer | Thời gian sống tối đa của quyền đọc, thường là 86400 giây. |
data.pin_grant.expires_at |
string | Thời hạn cấp quyền đọc hiện tại ở định dạng ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Thời hạn cấp quyền đọc tuyệt đối theo định dạng ISO-8601. Các thay đổi bảo mật có thể thu hồi quyền cấp trước thời hạn. |
Xóa Hộp Thư
Xóa một hộp thư đã sở hữu và kích hoạt việc dọn dẹp tin nhắn và tệp của nó. Các bản ghi hộp thư được giữ lại có thể bị xóa mềm nội bộ; địa chỉ không còn có thể sử dụng qua API.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
email
|
path | string | bắt buộc |
Địa chỉ email đầy đủ của hộp thư sở hữu cần xóa. Mã hoá URL địa chỉ; mã hoá dấu cộng thành %2B.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho hộp thư được bảo vệ: sử dụng unlock_token xóa một lần. Đầu tiên POST pin, scope=delete và action/target_id được trả về bởi phản hồi 423 tới URL mở khóa PIN. Token đọc không thể xóa. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
const response = await fetch('https://v1.tempmailg.com/api/emails/demo123@example.com', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/emails/demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/emails/demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/emails/demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
message |
string | Kết quả của việc xóa. Một tài nguyên không tồn tại sẽ trả về HTTP 404. |
Bí danh Gmail & Outlook
Tạo hộp thư bí danh Gmail và Outlook/Hotmail có uy tín cao.
Tạo bí danh Gmail
Tạo một hộp thư tạm thời alias Gmail mới thuộc sở hữu của người dùng đã xác thực.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
mode
|
body | string | tùy chọn |
Chế độ tạo: auto, dot, plus hoặc plus_dot. Cũng chấp nhận gmail_alias_mode. Nếu không cho phép chọn kiểu, sẽ sử dụng auto.
Mặc định:
auto
|
username
|
body | string | tùy chọn |
Tiền tố bí danh tùy chỉnh tùy chọn: 2 đến 32 ký tự ASCII là chữ cái hoặc chữ số, được chuẩn hóa thành chữ thường; phụ thuộc vào quyền tính năng. Cũng chấp nhận custom_username hoặc alias_username.
Mặc định:
Tự động tạo
|
domain
|
body | string | tùy chọn |
Sử dụng ngẫu nhiên, gmail.com hoặc googlemail.com; alias_domain cũng được chấp nhận. Việc bỏ qua hoặc không có quyền chọn miền sẽ sử dụng ngẫu nhiên.
Mặc định:
random
|
lifetime
|
body | string | tùy chọn |
các giá trị cho phép:
10m — 10 phút
1h — 1 giờ
2h — 2 giờ
1d — 1 ngày
1w — 1 Tuần
1m — 30 ngày
3m — 90 ngày
6m — 180 ngày
1y — 365 ngày
unlimited — Không giới hạn
Mặc định:
Thời gian sống mặc định của kế hoạch
|
pin_enabled
|
body | boolean | tùy chọn |
Bảo vệ PIN tùy chọn cho hộp thư mới, khi gói của bạn cho phép. Nó không thay đổi PIN của hộp thư đã tồn tại.
Mặc định:
false
|
pin
|
body | string | tùy chọn |
Yêu cầu khi pin_enabled là true: một PIN từ 6 đến 8 chữ số, được gửi dưới dạng chuỗi để giữ nguyên các số 0 ở đầu.
|
pin_confirmation
|
body | string | tùy chọn |
Bắt buộc khi pin_enabled là true. Phải khớp chính xác với pin.
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
mode (auto, dot, plus, plus_dot), username (tên người dùng bí danh tùy chỉnh), domain (ví dụ: gmail.com, googlemail.com), lifetime (các giá trị cho phép: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Bỏ qua thời gian sống, hoặc để trống, để sử dụng Thời gian sống Email Mặc định được cấu hình cho gói hàng tháng/năm hiện tại của bạn. Gửi một thời gian sống được phép như 1h để ghi đè lên mặc định đó. Không giới hạn chỉ được sử dụng khi được cấu hình làm mặc định của gói hoặc được yêu cầu và cho phép một cách rõ ràng. Các tham số trong phần body mailbox_lifetime và email_lifetime cũng được chấp nhận; giá trị không rỗng đầu tiên sẽ được ưu tiên theo thứ tự: lifetime, mailbox_lifetime, email_lifetime. Các giá trị không hợp lệ hoặc không được phép sẽ trả về HTTP 422 thay vì im lặng chọn giá trị mặc định.const response = await fetch('https://v1.tempmailg.com/api/gmail-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/gmail-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/gmail-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/gmail-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"id": 2305,
"pin_protected": false,
"email": "example+alias123@gmail.com",
"domain": "gmail.com",
"provider": "gmail_alias",
"expire_at": "2026-11-19T03:18:11+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:11+00:00",
"email_token": "encrypted-email-token"
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.id |
integer | ID hộp thư. Các ID, địa chỉ và token được tạo ra khác nhau cho mỗi hộp thư. |
data.pin_protected |
boolean | Cho biết hộp thư này có bảo vệ PIN hay không. Không trả về PIN hoặc hàm băm PIN. |
data.email |
string | Đã tạo địa chỉ hộp thư đầy đủ. |
data.domain |
string | Miền của hộp thư được tạo. |
data.provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
data.expire_at |
string|null | Ngày hết hạn hiệu lực dưới dạng dấu thời gian ISO-8601, hoặc null cho hộp thư không giới hạn. |
data.expires_in_seconds |
number|null | Giây còn lại không âm khi tính toán; có thể có giây phân số. Null có nghĩa là không giới hạn, không phải 0. |
data.mailbox_state |
string | Trạng thái hộp thư hiện tại: hoạt động, tạm dừng, đã hết hạn hoặc không hoạt động. |
data.receiving_enabled |
boolean | Liệu hộp thư này hiện có chấp nhận tin nhắn đến hay không. |
data.message_count |
integer | Số lượng tin nhắn tổng cộng đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.unread_message_count |
integer | Số lượng tin nhắn chưa đọc đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.last_message_received_at |
string|null | Thời gian nhận tin nhắn cuối cùng được biết theo định dạng ISO-8601, hoặc null khi không khả dụng. |
data.message_count_synced_at |
string|null | Thời gian đồng bộ đếm tin nhắn cuối cùng ở định dạng ISO-8601, hoặc null trước khi đồng bộ. |
data.created_at |
string|null | Thời gian tạo hộp thư theo định dạng ISO-8601. |
data.email_token |
string | Tham chiếu hộp thư được mã hóa không trong suốt. Nó không thay thế xác thực Bearer, kiểm tra quyền sở hữu hoặc ủy quyền PIN. |
data.pin_grant |
object | Có điều kiện: việc tạo hộp thư bảo vệ bằng PIN đang hoạt động trả về quyền đọc này; việc tạo bình thường không bảo vệ sẽ bỏ qua nó. |
data.pin_grant.mailbox_id |
integer | ID hộp thư mà quyền đọc có điều kiện được gắn vào. |
data.pin_grant.unlock_token |
string | Mã token đọc không trong suốt cho X-Mailbox-Unlock với cùng thông tin xác thực của chủ sở hữu. Giữ nó riêng tư và trong bộ nhớ; quyền đọc không cho phép xóa. |
data.pin_grant.scope |
string | Phạm vi được đọc cho quyền tạo có điều kiện. |
data.pin_grant.idle_timeout_seconds |
integer | Thời gian nhàn rỗi cho quyền đọc được phép, thường là 3600 giây. |
data.pin_grant.absolute_timeout_seconds |
integer | Thời gian sống tối đa của quyền đọc, thường là 86400 giây. |
data.pin_grant.expires_at |
string | Thời hạn cấp quyền đọc hiện tại ở định dạng ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Thời hạn cấp quyền đọc tuyệt đối theo định dạng ISO-8601. Các thay đổi bảo mật có thể thu hồi quyền cấp trước thời hạn. |
Tên miền bí danh Outlook
Lấy các miền bí danh Outlook / Hotmail đang hoạt động có sẵn để tạo hộp thư.
const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/domains', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/outlook-alias/domains', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/domains');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/outlook-alias/domains' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"domains": [
{
"domain": "outlook.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
},
{
"domain": "hotmail.com",
"type": "Outlook/Hotmail",
"selectable": true,
"locked": false,
"disabled_reason": null
}
]
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.domains |
array | Các miền Outlook/Hotmail đang hoạt động; một mảng trống là hợp lệ. |
data.domains[].domain |
string | Tên miền khả dụng. |
data.domains[].type |
string | Nhãn nhà cung cấp có thể đọc được. |
data.domains[].selectable |
boolean | Liệu tài khoản của bạn có thể chọn một cách rõ ràng miền này hay không. |
data.domains[].locked |
boolean | Liệu việc chọn miền một cách rõ ràng có bị khóa cho tài khoản của bạn hay không. |
data.domains[].disabled_reason |
string|null | Lý do lựa chọn miền bị khóa, hoặc null khi có thể chọn. |
Tạo bí danh Outlook
Tạo một hộp thư alias tạm thời Outlook / Hotmail mới thuộc sở hữu của người dùng đã xác thực.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
domain
|
body | string | tùy chọn |
Sử dụng ngẫu nhiên hoặc một miền từ GET /outlook-alias/domains; outlook_alias_domain cũng được chấp nhận. Nếu không có quyền chọn, sẽ sử dụng ngẫu nhiên.
Mặc định:
Miền khả dụng ngẫu nhiên
|
username
|
body | string | tùy chọn |
Tiền tố bí danh tùy chỉnh tùy chọn: 2 đến 32 ký tự ASCII là chữ cái hoặc chữ số, được chuẩn hóa thành chữ thường; phụ thuộc vào quyền tính năng. Cũng chấp nhận custom_username hoặc alias_username.
Mặc định:
Tự động tạo
|
lifetime
|
body | string | tùy chọn |
các giá trị cho phép:
10m — 10 phút
1h — 1 giờ
2h — 2 giờ
1d — 1 ngày
1w — 1 Tuần
1m — 30 ngày
3m — 90 ngày
6m — 180 ngày
1y — 365 ngày
unlimited — Không giới hạn
Mặc định:
Thời gian sống mặc định của kế hoạch
|
pin_enabled
|
body | boolean | tùy chọn |
Bảo vệ PIN tùy chọn cho hộp thư mới, khi gói của bạn cho phép. Nó không thay đổi PIN của hộp thư đã tồn tại.
Mặc định:
false
|
pin
|
body | string | tùy chọn |
Yêu cầu khi pin_enabled là true: một PIN từ 6 đến 8 chữ số, được gửi dưới dạng chuỗi để giữ nguyên các số 0 ở đầu.
|
pin_confirmation
|
body | string | tùy chọn |
Bắt buộc khi pin_enabled là true. Phải khớp chính xác với pin.
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
domain (ví dụ: outlook.com, hotmail.com), username (tên người dùng bí danh tùy chỉnh), lifetime (các giá trị cho phép: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). Bỏ qua thời gian sống, hoặc để trống, để sử dụng Thời gian sống Email Mặc định được cấu hình cho gói hàng tháng/năm hiện tại của bạn. Gửi một thời gian sống được phép như 1h để ghi đè lên mặc định đó. Không giới hạn chỉ được sử dụng khi được cấu hình làm mặc định của gói hoặc được yêu cầu và cho phép một cách rõ ràng. Các tham số trong phần body mailbox_lifetime và email_lifetime cũng được chấp nhận; giá trị không rỗng đầu tiên sẽ được ưu tiên theo thứ tự: lifetime, mailbox_lifetime, email_lifetime. Các giá trị không hợp lệ hoặc không được phép sẽ trả về HTTP 422 thay vì im lặng chọn giá trị mặc định.const response = await fetch('https://v1.tempmailg.com/api/outlook-alias/emails', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.post('https://v1.tempmailg.com/api/outlook-alias/emails', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/outlook-alias/emails');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request POST \
--url 'https://v1.tempmailg.com/api/outlook-alias/emails' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"id": 2306,
"pin_protected": false,
"email": "example+alias45@outlook.com",
"domain": "outlook.com",
"provider": "outlook_alias",
"expire_at": "2026-11-19T03:18:11+00:00",
"expires_in_seconds": 3599.75,
"mailbox_state": "active",
"receiving_enabled": true,
"message_count": 0,
"unread_message_count": 0,
"last_message_received_at": null,
"message_count_synced_at": null,
"created_at": "2026-11-19T02:18:11+00:00",
"email_token": "encrypted-email-token"
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.id |
integer | ID hộp thư. Các ID, địa chỉ và token được tạo ra khác nhau cho mỗi hộp thư. |
data.pin_protected |
boolean | Cho biết hộp thư này có bảo vệ PIN hay không. Không trả về PIN hoặc hàm băm PIN. |
data.email |
string | Đã tạo địa chỉ hộp thư đầy đủ. |
data.domain |
string | Miền của hộp thư được tạo. |
data.provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
data.expire_at |
string|null | Ngày hết hạn hiệu lực dưới dạng dấu thời gian ISO-8601, hoặc null cho hộp thư không giới hạn. |
data.expires_in_seconds |
number|null | Giây còn lại không âm khi tính toán; có thể có giây phân số. Null có nghĩa là không giới hạn, không phải 0. |
data.mailbox_state |
string | Trạng thái hộp thư hiện tại: hoạt động, tạm dừng, đã hết hạn hoặc không hoạt động. |
data.receiving_enabled |
boolean | Liệu hộp thư này hiện có chấp nhận tin nhắn đến hay không. |
data.message_count |
integer | Số lượng tin nhắn tổng cộng đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.unread_message_count |
integer | Số lượng tin nhắn chưa đọc đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
data.last_message_received_at |
string|null | Thời gian nhận tin nhắn cuối cùng được biết theo định dạng ISO-8601, hoặc null khi không khả dụng. |
data.message_count_synced_at |
string|null | Thời gian đồng bộ đếm tin nhắn cuối cùng ở định dạng ISO-8601, hoặc null trước khi đồng bộ. |
data.created_at |
string|null | Thời gian tạo hộp thư theo định dạng ISO-8601. |
data.email_token |
string | Tham chiếu hộp thư được mã hóa không trong suốt. Nó không thay thế xác thực Bearer, kiểm tra quyền sở hữu hoặc ủy quyền PIN. |
data.pin_grant |
object | Có điều kiện: việc tạo hộp thư bảo vệ bằng PIN đang hoạt động trả về quyền đọc này; việc tạo bình thường không bảo vệ sẽ bỏ qua nó. |
data.pin_grant.mailbox_id |
integer | ID hộp thư mà quyền đọc có điều kiện được gắn vào. |
data.pin_grant.unlock_token |
string | Mã token đọc không trong suốt cho X-Mailbox-Unlock với cùng thông tin xác thực của chủ sở hữu. Giữ nó riêng tư và trong bộ nhớ; quyền đọc không cho phép xóa. |
data.pin_grant.scope |
string | Phạm vi được đọc cho quyền tạo có điều kiện. |
data.pin_grant.idle_timeout_seconds |
integer | Thời gian nhàn rỗi cho quyền đọc được phép, thường là 3600 giây. |
data.pin_grant.absolute_timeout_seconds |
integer | Thời gian sống tối đa của quyền đọc, thường là 86400 giây. |
data.pin_grant.expires_at |
string | Thời hạn cấp quyền đọc hiện tại ở định dạng ISO-8601. |
data.pin_grant.absolute_expires_at |
string | Thời hạn cấp quyền đọc tuyệt đối theo định dạng ISO-8601. Các thay đổi bảo mật có thể thu hồi quyền cấp trước thời hạn. |
Tin nhắn & Tệp đính kèm
Lấy các hộp thư đến, đọc toàn bộ tin nhắn HTML/văn bản, và truyền luồng tệp đính kèm.
Liệt kê tin nhắn hộp thư
Truy xuất các bản tóm tắt tin nhắn có sẵn và siêu dữ liệu hộp thư. Các quét hộp đến tiêu chuẩn trả về một lô tin nhắn gần đây lên tới 25 tin; đây không phải là endpoint phân trang toàn bộ lịch sử. Sử dụng GET /messages/{messageId} để lấy nội dung đầy đủ và tệp đính kèm.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
email
|
query | string | bắt buộc |
Địa chỉ email đầy đủ của hộp thư sở hữu để đọc tin nhắn. Mã hoá URL cho giá trị truy vấn; mã hoá dấu cộng thành %2B.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho các hộp thư được bảo vệ: sử dụng một unlock_token để đọc. Đầu tiên POST pin và scope=read tới URL mở khóa PIN. Giữ xác thực Bearer thông thường của bạn. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages?email=demo123@example.com', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages?email=demo123@example.com', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages?email=demo123@example.com');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages?email=demo123@example.com' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"mailbox": "demo123@example.com",
"email_token": "encrypted-email-token",
"messages": [
{
"is_seen": false,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"receivedAt": "2026-11-19 02:18:11",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"otp": null,
"otp_locked": false,
"verification_link": null,
"verification_link_locked": false
}
],
"mailbox_provider": "standard",
"mailbox_state": "active",
"expire_at": "2026-11-20T02:18:11+00:00",
"expires_in_seconds": 86399.75,
"receiving_enabled": true,
"mailbox_limit": {
"limit": 50,
"limit_label": "50",
"active_count": 1,
"paused_count": 0,
"paused_mailboxes": [],
"remaining": 49,
"remaining_label": "49",
"reached": false,
"blocked": false,
"provider": "standard"
},
"message_count": 1,
"unread_message_count": 1,
"last_message_received_at": "2026-11-19T02:18:11+00:00",
"message_count_synced_at": "2026-11-19T02:18:11+00:00"
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
mailbox |
string | Địa chỉ hộp thư mà các tin nhắn đã được yêu cầu. |
email_token |
string | Tham chiếu hộp thư được mã hóa không trong suốt; vẫn cần xác thực bình thường. |
mailbox_provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
messages |
array | Tóm tắt tin nhắn. Hộp thư rỗng trả về một mảng trống; lấy một tin nhắn duy nhất để có nội dung và tệp đính kèm. |
expire_at |
string|null | Ngày hết hạn hiệu lực dưới dạng dấu thời gian ISO-8601, hoặc null cho hộp thư không giới hạn. |
expires_in_seconds |
number|null | Giây còn lại không âm khi tính toán; có thể có giây phân số. Null có nghĩa là không giới hạn, không phải 0. |
mailbox_state |
string | Trạng thái hộp thư hiện tại: hoạt động, tạm dừng, đã hết hạn hoặc không hoạt động. |
receiving_enabled |
boolean | Liệu hộp thư này hiện có chấp nhận tin nhắn đến hay không. |
message_count |
integer | Số lượng tin nhắn tổng cộng đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
unread_message_count |
integer | Số lượng tin nhắn chưa đọc đã biết; nó có thể phản ánh lần đồng bộ hộp thư cuối cùng. |
last_message_received_at |
string|null | Thời gian nhận tin nhắn cuối cùng được biết theo định dạng ISO-8601, hoặc null khi không khả dụng. |
message_count_synced_at |
string|null | Thời gian đồng bộ đếm tin nhắn cuối cùng ở định dạng ISO-8601, hoặc null trước khi đồng bộ. |
mailbox_limit.limit |
integer | Giới hạn hộp thư hoạt động cho nhà cung cấp này; -1 có nghĩa là không giới hạn. |
mailbox_limit.limit_label |
string | Nhãn hiển thị cho giới hạn hộp thư. |
mailbox_limit.active_count |
integer | Số lượng hộp thư hoạt động cho nhà cung cấp này. |
mailbox_limit.paused_count |
integer | Số lượng hộp thư bị tạm dừng cho nhà cung cấp này. |
mailbox_limit.paused_mailboxes |
array<string> | Địa chỉ bị tạm dừng do giới hạn hộp thư. |
mailbox_limit.remaining |
integer | Số khe hộp thư hoạt động còn lại; -1 có nghĩa là không giới hạn. Đây không phải là hạn ngạch yêu cầu API. |
mailbox_limit.remaining_label |
string | Hiển thị nhãn cho các khe hộp thư còn lại. |
mailbox_limit.reached |
boolean | Liệu giới hạn hộp thư hoạt động đã đạt được chưa. |
mailbox_limit.blocked |
boolean | Liệu giới hạn hộp thư hoạt động có bằng không hay không. |
mailbox_limit.provider |
string|null | Nhà cung cấp mà giới hạn hộp thư áp dụng. |
messages[].id |
string | ID tin nhắn không rõ được sử dụng bởi các điểm cuối tin nhắn đơn, xóa và tệp đính kèm. |
messages[].is_seen |
boolean | Liệu tin nhắn có được đánh dấu là đã đọc hay không. |
messages[].subject |
string | Tiêu đề tin nhắn. |
messages[].from |
string | Tên hiển thị hoặc địa chỉ của người gửi. |
messages[].from_email |
string | Địa chỉ email người gửi. |
messages[].receivedAt |
string | Thời gian nhận theo múi giờ của ứng dụng, định dạng YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | Phát hiện mã một lần khi có sẵn và được phép; nếu không thì null. |
messages[].otp_locked |
boolean | Liệu mã một lần được phát hiện có bị ẩn bởi quyền tính năng hay không. |
messages[].verification_link |
string|null | Phát hiện URL xác minh khi có sẵn và được phép; nếu không thì null. |
messages[].verification_link_locked |
boolean | Liệu liên kết xác minh được phát hiện có bị ẩn bởi quyền tính năng hay không. |
messages[].from_name |
string|null | Trường tóm tắt Outlook: tên người gửi gốc. Không có trong tóm tắt tiêu chuẩn và Gmail. |
messages[].snippet |
string|null | Trường tóm tắt Outlook: bản xem trước tin nhắn ngắn. |
messages[].received_at |
string|null | Trường tóm tắt Outlook: thời gian nhận theo chuẩn ISO-8601, nếu biết. |
messages[].has_attachments |
boolean | Trường tóm tắt Outlook: liệu có siêu dữ liệu tệp đính kèm hay không. Tính khả dụng tải xuống được kiểm tra riêng. |
Lấy tin nhắn đơn
Truy xuất một tin nhắn thuộc sở hữu bằng ID tin nhắn không rõ ràng của nó. Trả về các định dạng nội dung và siêu dữ liệu tệp đính kèm. Các trường nội dung phụ thuộc vào định dạng tin nhắn; Outlook thêm các trường đặc thù của nhà cung cấp được liệt kê bên dưới.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
messageId
|
path | string | bắt buộc |
ID tin nhắn duy nhất được trả về trong danh sách tin nhắn.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho các hộp thư được bảo vệ: sử dụng một unlock_token để đọc. Đầu tiên POST pin và scope=read tới URL mở khóa PIN. Giữ xác thực Bearer thông thường của bạn. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"data": {
"is_seen": true,
"subject": "Welcome to Temp Mail",
"from": "Example Sender",
"from_email": "hello@example.org",
"to": "demo123@example.com",
"mailbox_provider": "standard",
"receivedAt": "2026-11-19 02:18:11",
"id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
"html": true,
"html_content": "<p>Hello from the inbox.</p>",
"text_content": "<pre>Hello from the inbox.</pre>",
"content": "<p>Hello from the inbox.</p>",
"attachments": [
{
"name": "file.txt",
"extension": "txt",
"size": 91,
"url": "https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt"
}
]
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
data.id |
string | ID tin nhắn không công khai. |
data.is_seen |
boolean | Trạng thái đã đọc của tin nhắn. Đọc có thể đánh dấu là đã xem; dữ liệu đã lưu trong bộ nhớ đệm có thể phản ánh trạng thái trước đó. |
data.subject |
string | Tiêu đề tin nhắn. |
data.from |
string | Tên hiển thị hoặc địa chỉ của người gửi. |
data.from_email |
string | Địa chỉ email người gửi. |
data.to |
string | Địa chỉ hộp thư người nhận. |
data.mailbox_provider |
string | Nhà cung cấp hộp thư: standard, gmail_alias, hoặc outlook_alias. |
data.receivedAt |
string | Thời gian nhận theo múi giờ của ứng dụng, định dạng YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | Liệu tin nhắn có phần thân HTML hay không. |
data.html_content |
string | Thân HTML khi có. Các tin nhắn tiêu chuẩn không có HTML có thể bỏ qua trường này. Xem nội dung tin nhắn là không đáng tin cậy. |
data.text_content |
string | Nội dung văn bản khi có; Các tin nhắn tiêu chuẩn có thể chứa văn bản đã được escape trong phần tử pre hoặc bỏ qua trường này. |
data.content |
string | Nội dung ưu tiên để hiển thị, thường là HTML khi có sẵn. |
data.attachments |
array | Siêu dữ liệu tệp đính kèm, hoặc một mảng rỗng. Tải xuống yêu cầu xác thực bình thường và ủy quyền PIN áp dụng. |
data.attachments[].name |
string | Tên tệp để mã hóa URL thành một đoạn đường dẫn duy nhất khi tải xuống. |
data.attachments[].size |
integer | Kích thước tệp đính kèm tính bằng byte. |
data.attachments[].url |
string | URL tải xuống API Người dùng đã xác thực được thêm vào các tệp đính kèm với tên tệp. URL không đảm bảo rằng tệp cục bộ có sẵn. |
data.attachments[].extension |
string | Trường siêu dữ liệu Standard/Gmail: phần mở rộng tệp khi được cung cấp. |
data.attachments[].id |
string | Trường siêu dữ liệu Outlook: ID tệp đính kèm của nhà cung cấp. |
data.attachments[].content_type |
string | Trường siêu dữ liệu Outlook: loại nội dung MIME. |
data.from_name |
string|null | Trường chi tiết Outlook: tên người gửi gốc. |
data.to_email |
string|null | Trường chi tiết Outlook: địa chỉ người nhận gốc. |
data.received_at |
string|null | Trường chi tiết Outlook: thời gian nhận theo chuẩn ISO-8601. |
data.has_html |
boolean | Trường chi tiết Outlook: liệu có tồn tại phần thân HTML hay không. |
Xóa tin nhắn
Xóa một tin nhắn thuộc sở hữu đơn lẻ.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
messageId
|
path | string | bắt buộc |
Chuỗi ID tin nhắn duy nhất để xóa vĩnh viễn.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho hộp thư được bảo vệ: sử dụng unlock_token xóa một lần. Đầu tiên POST pin, scope=delete và action/target_id được trả về bởi phản hồi 423 tới URL mở khóa PIN. Token đọc không thể xóa. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | tùy chọn |
Yêu cầu cho việc tạo hoặc xóa được bảo vệ bằng PIN: một khóa ổn định từ 16 đến 128 ký tự. Thử lại yêu cầu giống hệt với cùng một khóa để tránh công việc trùng lặp.
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', {
method: 'DELETE',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.delete('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request DELETE \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| Trường | Loại | Mô Tả |
|---|---|---|
status |
boolean | Liệu thao tác có thành công hay không. |
message |
string | Kết quả của việc xóa. Một tài nguyên không tồn tại sẽ trả về HTTP 404. |
Tải xuống tệp đính kèm
Tải xuống tệp đính kèm từ tin nhắn thuộc sở hữu.
| Tham số | Vị trí | Loại | Trạng thái | Mô Tả |
|---|---|---|---|---|
messageId
|
path | string | bắt buộc |
ID của tin nhắn chứa tệp.
|
filename
|
path | string | bắt buộc |
Tên tệp và phần mở rộng của tệp đính kèm để tải xuống.
|
X-Mailbox-Unlock
|
header | string | tùy chọn |
Tiêu đề, chỉ dành cho các hộp thư được bảo vệ: sử dụng một unlock_token để đọc. Đầu tiên POST pin và scope=read tới URL mở khóa PIN. Giữ xác thực Bearer thông thường của bạn. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
const response = await fetch('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const blob = await response.blob();
const downloadUrl = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = downloadUrl;
link.download = 'file.txt';
document.body.appendChild(link);
link.click();
link.remove();
window.URL.revokeObjectURL(downloadUrl);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt', headers=headers, stream=True, timeout=30)
response.raise_for_status()
with open('file.txt', 'wb') as handle:
for chunk in response.iter_content(chunk_size=8192):
if chunk:
handle.write(chunk)
<?php
$fileHandle = fopen('file.txt', 'w');
$ch = curl_init('https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_FILE => $fileHandle,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
if (curl_exec($ch) === false) {
fclose($fileHandle);
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
fclose($fileHandle);
curl --request GET \
--url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY' \
--output file.txt
| Trường | Loại | Mô Tả |
|---|---|---|
Content-Disposition |
header | Phản hồi thành công tải xuống tên tệp đã yêu cầu. |
body |
binary | Dữ liệu tệp dưới dạng byte khi thành công, không phải JSON. Lỗi trả về JSON với trạng thái không phải 2xx. |
Giới hạn tốc độ & Hạn ngạch
Giám sát ngân sách yêu cầu thời gian thực, giới hạn tốc độ và hạn ngạch tài khoản mà không tiêu tốn tín dụng.
Giới hạn tốc độ & Hạn ngạch
Kiểm tra giới hạn tốc độ và trạng thái hạn ngạch hiện tại của bạn mà không tiêu tốn bất kỳ lượt sử dụng API nào. Điểm cuối này không tính vào hạn ngạch và không trừ tín dụng API hàng tháng (giới hạn bảo vệ lạm dụng: 60 yêu cầu/phút).
const response = await fetch('https://v1.tempmailg.com/api/rate-limit', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
import requests
headers = {
'Authorization': 'Bearer YOUR_USER_API_KEY',
'Accept': 'application/json',
}
response = requests.get('https://v1.tempmailg.com/api/rate-limit', headers=headers, timeout=30)
response.raise_for_status()
print(response.json())
<?php
$ch = curl_init('https://v1.tempmailg.com/api/rate-limit');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_USER_API_KEY',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($statusCode, json_decode($response, true));
curl --request GET \
--url 'https://v1.tempmailg.com/api/rate-limit' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_USER_API_KEY'
Phản hồi minh họa sử dụng dữ liệu tổng hợp. ID, địa chỉ, token, dấu thời gian, giới hạn và số lượng kế hoạch thay đổi. Thời gian sống mẫu không ghi đè mặc định kế hoạch của bạn. Mô tả các trường phản hồi xác định các trường có thể null và các trường đặc thù của nhà cung cấp.
Ví dụ về phản hồi
200 OK • JSON{
"status": "success",
"data": {
"limit": 60,
"remaining": 45,
"reset": 32,
"plan": "premium",
"monthly_limit": 50000,
"monthly_remaining": 48210,
"purchased_credits": 5000,
"quota": {
"enabled": true,
"user_api_status": true,
"plan_name": "Premium Plan",
"period": "2026-10",
"base_limit": 50000,
"extra_requests": 0,
"monthly_limit": 50000,
"monthly_remaining": 48210,
"used": 1790,
"purchased_credits": 5000,
"bonus_credits": 1000,
"direct_purchased_credits": 4000,
"remaining": 53210,
"unlimited": false,
"usage_percent": 3,
"reset_at": "2026-11-01T00:00:00+00:00"
}
}
}
| Trường | Loại | Mô Tả |
|---|---|---|
data.limit |
integer|string | Giới hạn yêu cầu tài khoản mỗi phút. Chuỗi unlimited biểu thị ngân sách phút không giới hạn; điều này độc lập với hạn mức hàng tháng. |
data.remaining |
integer|string | Số khe ngân sách phút còn lại trong tài khoản, hoặc chuỗi unlimited. Giá trị dương không có nghĩa là còn lại tín dụng API. |
data.reset |
integer | Giây cho cửa sổ phút của tài khoản, không phải việc đặt lại hạn ngạch hàng tháng. Ngân sách phút bị vô hiệu hoá hoặc không giới hạn có thể giữ giá trị danh nghĩa 60 giây; điều này không hứa hẹn quyền truy cập sau khi chờ đợi. |
data.plan |
string | Thẻ gói hiện tại. Tên gói có thể đọc được được cung cấp riêng trong data.quota.plan_name. |
data.quota.enabled |
boolean | Cho biết việc truy cập API toàn cầu và theo gói/điểm tín dụng có được bật hay không. Điều này không cho biết dung lượng còn lại hoặc thay thế công tắc API của người dùng. |
data.quota.user_api_status |
boolean | Liệu người dùng đã bật công tắc API Người dùng của họ hay chưa. Các hoạt động yêu cầu công tắc này cũng như quyền truy cập đã bật và dung lượng khả dụng. |
data.quota.plan_name |
string | Tên dễ đọc của gói hiện tại. |
data.quota.period |
string | Thời gian sử dụng theo tháng lịch ở định dạng YYYY-MM, sử dụng múi giờ của ứng dụng; không nhất thiết là kỳ thanh toán của thuê bao. |
data.quota.base_limit |
integer | Hạn mức gói hàng tháng cơ bản. Giá trị -1 có nghĩa là không giới hạn. |
data.quota.extra_requests |
integer | Phép dùng hàng tháng bổ sung được cấp cho kỳ sử dụng hiện tại; tách biệt khỏi các tín dụng đã mua. |
data.quota.monthly_limit |
integer | Phép cho phép cơ bản cộng với các yêu cầu bổ sung trong kỳ hiện tại. Giá trị -1 có nghĩa là không giới hạn. Tín dụng đã mua không được bao gồm. |
data.quota.monthly_remaining |
integer|null | Số dư hạn mức hàng tháng có giới hạn còn lại, hoặc null khi hạn mức hàng tháng không giới hạn. Null không được hiểu là zero. |
data.quota.used |
integer | Các hoạt động API thành công, được tính trong khoảng thời gian sử dụng hiện tại, bao gồm các hoạt động sử dụng tín dụng. Kiểm tra trạng thái không làm tăng giá trị này. |
data.quota.purchased_credits |
integer | Số dư tín dụng hiện tại, bao gồm tín dụng thưởng của gói đang hoạt động. Tín dụng thưởng không được cộng thêm vào số dư này lần thứ hai. |
data.quota.bonus_credits |
integer | Phần thưởng kế hoạch hoạt động của số dư tín dụng; chi tiết của purchased_credits, không phải dung lượng bổ sung. |
data.quota.direct_purchased_credits |
integer | Số dư tín dụng không bao gồm phần thưởng gói đang hoạt động. Giá trị này cộng với bonus_credits bằng purchased_credits. |
data.quota.remaining |
integer|null | Số dư hạn mức hàng tháng còn lại cộng với số dư tín dụng hiện tại, không tính trùng lặp các phần thưởng. Null có nghĩa là hạn mức hàng tháng không giới hạn. Quyền tính năng cá nhân và các giới hạn yêu cầu khác vẫn áp dụng. |
data.quota.unlimited |
boolean | Liệu hạn mức hàng tháng có không giới hạn hay không. Điều này không làm cho ngân sách phút của tài khoản hoặc các giới hạn tính năng khác trở nên không giới hạn. |
data.quota.usage_percent |
integer | Phần trăm làm tròn tương thích với bảng điều khiển từ 0 đến 100: đã sử dụng chia cho (đã sử dụng + còn lại), nhân với 100. Nó bao gồm khả năng tín dụng khả dụng, vì vậy việc nạp lại có thể làm giảm phần trăm. Giá trị là 0 cho hạn ngạch không giới hạn hoặc pool có kích thước bằng 0; nó không phải là phần trăm giới hạn tốc độ mỗi phút hoặc quyết định truy cập. |
data.quota.reset_at |
string | Dấu thời gian ISO-8601 kèm độ lệch múi giờ cho lần đặt lại hạn ngạch tháng lịch tiếp theo. Đây không phải là ngày hết hạn đăng ký, và việc đặt lại hàng tháng không làm đầy lại các tín dụng đã mua. |
status |
string | Kết quả thành công nguyên văn cho điểm cuối trạng thái này. Các điểm cuối hộp thư thành công khác sử dụng giá trị boolean true. |
data.monthly_limit |
integer | Bí danh tương thích của trường data.quota tương ứng; không thêm lại khi tính toán số dư. |
data.monthly_remaining |
integer|null | Bí danh tương thích của trường data.quota tương ứng; không thêm lại khi tính toán số dư. |
data.purchased_credits |
integer | Bí danh tương thích của trường data.quota tương ứng; không thêm lại khi tính toán số dư. |
Webhook Mailbox (Báo động thực thời)
Thay vì liên tục gọi API REST (GET /messages) để kiểm tra thư đến, hãy cấu hình Webhook để đẩy tin nhắn mới đến máy chủ hoặc luồng tự động của bạn ngay lập tức.
Sự kiện Webhook được hỗ trợ
Mỗi webhook có thể đăng ký theo một hoặc nhiều loại sự kiện. Điểm cuối của bạn nhận được thông báo sự kiện mỗi khi một trong những sự kiện này được kích hoạt.
Được gửi ngay lập tức mỗi khi có tin nhắn mới đến hộp thư đã chọn.
Được gửi khi hộp thư tạm thời hết hạn và việc xử lý webhook bị tạm dừng.
Được gửi khi hộp thư đã hết hạn trở lại hoạt động theo quy tắc gói.
Được gửi ngay trước khi webhook và hộp thư của nó bị xóa.
Yêu cầu Header & Kiểm tra Chữ ký HMAC
Mỗi lần giao hàng webhook đều chứa các header bảo mật đặc biệt. Hãy sử dụng header **X-TempMailg-Signature** để xác minh rằng các yêu cầu đến đã được gửi chính thức bởi TempMailg và không bị thay đổi.
| Tên Tiêu Đề | Giá trị ví dụ | Mô Tả |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | Định danh tiêu chuẩn cho worker giao webhook. |
X-TempMailg-Event |
email.received | Loại sự kiện đã kích hoạt việc giao hàng này. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | UUID duy nhất được gán cho lần cố gắng giao hàng này. |
X-TempMailg-Timestamp |
1725192000 | Dấu thời gian Unix epoch cho biết thời điểm yêu cầu được khởi tạo. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | Chữ ký HMAC-SHA256 được tính từ {timestamp}.{raw_body} bằng cách sử dụng bí mật của bạn. |
X-TempMailg-Test |
false | Đúng khi được gửi bởi tính năng "Send Test Ping" trong bảng điều khiển của bạn. |
Chuỗi ký tự này được tính toán bằng cách sử dụng HMAC với SHA256:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
Dữ liệu Sự kiện Mẫu (email.received)
Được gửi dưới dạng application/json trong thân yêu cầu HTTP POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:18:12+00:00",
"test": false,
"mailbox": {
"id": 1024,
"email": "developer@v1.tempmailg.com"
},
"data": {
"message_id": "7a8b9c0d1e2f",
"subject": "Your Verification Code: 948201",
"from": "auth@service.com",
"to": "developer@v1.tempmailg.com",
"date": "2026-11-19T02:18:12+00:00",
"attachments_count": 0,
"text_preview": "Hello, your one-time verification code is 948201. It will expire in 10 minutes.",
"email_url": "https://tempmailg.com/mailbox/1024?message=7a8b9c0d1e2f",
"inbox_url": "https://tempmailg.com/mailbox/1024"
}
}
Ví dụ triển khai Receiver
Chọn ngôn ngữ của bạn để xem cách nhận webhook và xác minh chữ ký HMAC một cách an toàn.
const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = 'your_webhook_signing_secret';
// Capture raw body buffer for HMAC-SHA256 signature verification
app.use(express.json({
verify: (req, res, buf) => {
req.rawBody = buf.toString('utf8');
}
}));
app.post('/webhook', (req, res) => {
const timestamp = req.headers['x-tempmailg-timestamp'];
const signatureHeader = req.headers['x-tempmailg-signature'] || '';
// Calculate HMAC-SHA256 signature
const expectedSignature = 'sha256=' + crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${timestamp}.${req.rawBody}`)
.digest('hex');
// Verify signature
if (signatureHeader !== expectedSignature) {
return res.status(401).json({ error: 'Invalid webhook signature' });
}
const { event, mailbox, data } = req.body;
console.log(`[Event: ${event}] Mailbox: ${mailbox.email}`);
if (event === 'email.received') {
console.log(`From: ${data.from}`);
console.log(`Subject: ${data.subject}`);
console.log(`Preview: ${data.text_preview}`);
}
// Acknowledge receipt with HTTP 200
res.status(200).json({ received: true });
});
app.listen(3000, () => console.log('Webhook receiver running on port 3000'));
from flask import Flask, request, jsonify
import hmac
import hashlib
app = Flask(__name__)
WEBHOOK_SECRET = b"your_webhook_signing_secret"
@app.route("/webhook", methods=["POST"])
def handle_webhook():
timestamp = request.headers.get("X-TempMailg-Timestamp", "")
signature_header = request.headers.get("X-TempMailg-Signature", "")
# Calculate expected HMAC-SHA256 signature
raw_body = request.get_data()
signed_payload = f"{timestamp}.".encode("utf-8") + raw_body
expected_signature = "sha256=" + hmac.new(
WEBHOOK_SECRET, signed_payload, hashlib.sha256
).hexdigest()
# Verify signature securely
if not hmac.compare_digest(signature_header, expected_signature):
return jsonify({"error": "Invalid signature"}), 401
payload = request.get_json()
event = payload.get("event")
mailbox = payload.get("mailbox", {}).get("email")
data = payload.get("data", {})
print(f"[{event}] Mailbox: {mailbox}")
if event == "email.received":
print(f"From: {data.get('from')}")
print(f"Subject: {data.get('subject')}")
print(f"Preview: {data.get('text_preview')}")
# Return 200 OK to acknowledge receipt
return jsonify({"received": True}), 200
if __name__ == "__main__":
app.run(port=5000)
<?php
$secret = 'your_webhook_signing_secret';
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_TEMPMAILG_TIMESTAMP'] ?? '';
$receivedSignature = $_SERVER['HTTP_X_TEMPMAILG_SIGNATURE'] ?? '';
// Calculate HMAC-SHA256 signature
$expectedSignature = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
// Verify signature
if (!hash_equals($expectedSignature, $receivedSignature)) {
http_response_code(401);
echo json_encode(['error' => 'Invalid signature']);
exit;
}
$payload = json_decode($rawBody, true);
$event = $payload['event'] ?? '';
$mailbox = $payload['mailbox']['email'] ?? '';
$data = $payload['data'] ?? [];
if ($event === 'email.received') {
$sender = $data['from'] ?? '';
$subject = $data['subject'] ?? '';
$preview = $data['text_preview'] ?? '';
// Process new incoming email...
}
// Acknowledge receipt
http_response_code(200);
echo json_encode(['received' => true]);
Nền tảng được hỗ trợ & Tích hợp Tự động hoá
Webhooks TempMailg hoạt động ngay lập tức với các điểm cuối HTTPS tiêu chuẩn và các nền tảng không mã/tự động hàng đầu:
Lỗi phổ biến và khắc phục sự cố
Đây là các mã phản hồi phổ biến nhất bạn có thể thấy trong khi tích hợp API người dùng.
Token Bearer không hợp lệ, thiếu hoặc đã bị thu hồi.
Quyền sở hữu, quyền tính năng, quyền truy cập miền hoặc kích thước tệp đính kèm đã ngăn chặn thao tác. Kiểm tra mã phản hồi và tin nhắn.
Tài nguyên không được tìm thấy trên máy chủ được phép hoặc không thuộc về người dùng.
Khóa thao tác đã được sử dụng lại với các chi tiết khác nhau, một thao tác khác đang chờ xử lý, hoặc bảo mật hộp thư đã thay đổi. Kiểm tra mã trước khi thử lại.
Hộp thư đã hết hạn hoặc không hoạt động.
Tham số không hợp lệ, thời gian sống không được phép, dung lượng bí danh không khả dụng, cài đặt PIN không hợp lệ hoặc thiếu/không hợp lệ Idempotency-Key đã ngăn chặn hoạt động.
Một hộp thư được bảo vệ cần một token X-Mailbox-Unlock có phạm vi hợp lệ. Sử dụng hành động và target_id từ phản hồi để xóa. Các yêu cầu khóa hoặc khôi phục phải được giải quyết trước khi thử lại.
Giới hạn yêu cầu, kế hoạch bị vô hiệu hoá, hạn ngạch đã cạn, hoặc thời gian chờ đã ngăn chặn thao tác. Kiểm tra lý do và tiêu đề ngân sách khả dụng. Retry-After là tùy chọn.
Máy chủ không thể hoàn thành thao tác. Đối với việc tạo hoặc xóa được bảo vệ, hãy giữ nguyên yêu cầu và Idempotency-Key khi thử lại.
Không thể xác minh việc lưu trữ bảo vệ hoặc phối hợp. Hãy thử lại sau thời gian trì hoãn được chỉ định. Phản hồi này không phải là thanh toán thất bại.
Danh sách kiểm tra nhanh
- 401 Unauthorized - Mã thông báo Bearer bị thiếu, sai, bị thu hồi hoặc sao chép không chính xác.
- 403 Forbidden - Kế hoạch hiện tại không có quyền truy cập API người dùng ngay bây giờ.
- 404 Not Found - Tài nguyên không tìm thấy hoặc tham số không hợp lệ
- 410 Gone / Expired - Hộp thư đã hết hạn hoặc không còn hoạt động.
- 429 Rate Limited - Kiểm tra lý do phản hồi và các tiêu đề ngân sách. Retry-After chỉ áp dụng cho các giới hạn thời gian; việc hết tín dụng hoặc truy cập bị vô hiệu hoá có thể yêu cầu thay đổi tài khoản.
Bước tiếp theo được khuyến nghị
Nếu bạn đã đăng nhập, hãy mở API Management trước và xác nhận trạng thái khóa, hạn ngạch, kế hoạch truy cập và URL cơ sở API người dùng chính xác trước khi gỡ lỗi ứng dụng bên ngoài của bạn.