TempMailg Tài Liệu API

Sử dụng tài liệu này để tạo khóa API cá nhân, kết nối máy chủ API người dùng chuyên dụng, đọc tin nhắn hộp thư, quản lý hộp thư thuộc sở hữu và tích hợp Temp Mail vào ứng dụng hoặc tự động hóa của riêng bạn.

Địa Chỉ Cơ Sở API Người Dùng

Định dạng yêu cầu Sử dụng khóa API chỉ trong tiêu đề Authorization Bearer và giữ cho các URL điểm cuối sạch sẽ.

Đăng nhập để tạo khóa API Tạo tài khoản

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.yourdomain.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 dashboard và từ tiêu đề hạn ngạch được trả về trong mọi 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.

Nếu API trả về 404 Đảm bảo bạn đang gọi host API người dùng chuyên dụng chính xác như được hiển thị trong trang Quản lý API của bạn.

Khóa truy cập API

Đăng nhập để tạo khóa API cá nhân của bạn và xem chi tiết hạn ngạch trực tiếp.

Đăng Nhập Đăng ký

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.

Tính khả dụng của khóa Khóa API người dùng của bạn vẫn hiển thị bên trong trang Quản lý API của bạn cho đến khi bạn tạo lại hoặc thu hồi nó.

Tiêu đề yêu cầu

Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json

Tiêu đề hạn ngạch được trả về trong mọi phản hồi

Các giá trị hạn ngạch này chỉ tăng sau các phản hồi 2xx thành công.

X-RateLimit-Limit: 50000
X-RateLimit-Used: 124
X-RateLimit-Remaining: 49876
X-RateLimit-Reset: 2026-05-01T00:00:00+05:00

Điểm cuối API người dùng

Mọi điểm cuối dưới đây sử dụng cùng một URL cơ sở và cùng một mã thông báo Bearer. Yêu cầu hộp thư, tin nhắn và tệp được kiểm tra đối với tài khoản người dùng được xác thực.

GET https://v1.tempmailg.com/api/domains?type={type}

Lấy các miền được phép cho kế hoạch và tài khoản người dùng hiện tại.

Giá trị loại được phép: free, premium, all. Kế hoạch miễn phí chỉ có thể sử dụng free. Kế hoạch cao cấp có thể sử dụng free, premium, hoặc all.

Lấy miền được phép

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'

Ví dụ về phản hồi

{
    "status": true,
    "data": {
        "requested_type": "free",
        "allowed_types": [
            "free"
        ],
        "domains": [
            {
                "domain": "example.com",
                "type": "Free",
                "custom": false
            }
        ]
    }
}

POST https://v1.tempmailg.com/api/emails

Tạo một hộp thư đến ngẫu nhiên mới thuộc sở hữu của người dùng đã xác thực.

Tạo hộp thư đến ngẫu nhiên

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'

Ví dụ về phản hồi

{
    "status": true,
    "data": {
        "id": 2301,
        "email": "randombox@example.com",
        "domain": "example.com",
        "expire_at": "2026-06-28T09:48:52+00:00",
        "expires_in_seconds": 600,
        "created_at": "2026-06-28T09:38:52+00:00",
        "email_token": "encrypted-email-token"
    }
}

POST https://v1.tempmailg.com/api/emails/{email}/{username}/{domain}

Cập nhật hoặc chuyển đổi một hộp thư đến thuộc sở hữu hiện có sang một tên người dùng mới và miền được phép.

Sử dụng hộp thư đến thuộc sở hữu hiện có trong {email}.

Cập nhật hộp thư đến thuộc sở hữu

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'

Ví dụ về phản hồi

{
    "status": true,
    "data": {
        "id": 2302,
        "email": "demo123@example.com",
        "domain": "example.com",
        "expire_at": "2026-06-28T09:48:52+00:00",
        "expires_in_seconds": 600,
        "created_at": "2026-06-28T09:38:52+00:00",
        "email_token": "encrypted-email-token"
    }
}

DELETE https://v1.tempmailg.com/api/emails/{email}

Xóa Hộp Thư Thuộc Sở Hữu.

Xóa hộp thư đến thuộc sở hữu

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'

Ví dụ về phản hồi

{
    "status": true,
    "message": "Email has been successfully deleted."
}

GET https://v1.tempmailg.com/api/messages?email={email}

Liệt kê các tin nhắn cho hộp thư đến thuộc sở hữu.

Tham số truy vấn email phải thuộc tài khoản người dùng đã xác thực.

Đọc tin nhắn hộp thư

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'

Ví dụ về phản hồi

{
    "status": true,
    "mailbox": "randombox@example.com",
    "messages": [
        {
            "is_seen": false,
            "subject": "Welcome to Temp Mail",
            "from": "Example Sender",
            "from_email": "hello@example.org",
            "to": "randombox@example.com",
            "receivedAt": "2026-06-28 09:38:52",
            "id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
            "html": true,
            "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"
                }
            ]
        }
    ]
}

GET https://v1.tempmailg.com/api/messages/{messageId}

Đọc một tin nhắn thuộc sở hữu đơn lẻ.

Đọc một tin nhắn

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'

Ví dụ về phản hồi

{
    "status": true,
    "data": {
        "is_seen": true,
        "subject": "Welcome to Temp Mail",
        "from": "Example Sender",
        "from_email": "hello@example.org",
        "to": "randombox@example.com",
        "receivedAt": "2026-06-28 09:38:52",
        "id": "ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1",
        "html": true,
        "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"
            }
        ]
    }
}

DELETE https://v1.tempmailg.com/api/messages/{messageId}

Xóa một tin nhắn thuộc sở hữu đơn lẻ.

Xóa một tin nhắn

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'

Ví dụ về phản hồi

{
    "status": true,
    "message": "Message was deleted successfully."
}

GET https://v1.tempmailg.com/api/messages/{messageId}/attachments/{filename}

Tải xuống tệp đính kèm từ tin nhắn thuộc sở hữu.

Endpoint này tải tệp trực tiếp.

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

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

Hành vi tải xuống Điểm cuối này trả về tệp được yêu cầu trực tiếp thay vì một cơ thể JSON.

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.

401 Token Bearer không hợp lệ hoặc thiếu.

403 Truy cập API người dùng bị tắt cho kế hoạch người dùng hiện tại.

404 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.

410 Hộp thư đã hết hạn hoặc không hoạt động.

422 Xác thực thất bại hoặc hộp thư / miền được yêu cầu không được phép.

429 Hạn ngạch API người dùng hàng tháng đã được vượt quá.

Danh sách kiểm tra nhanh

401 - 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 - 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 - Hộp thư, tin nhắn hoặc tệp không thuộc về người dùng đó hoặc host sai đang được sử dụng.
410 - Hộp thư đã hết hạn hoặc không còn hoạt động.
429 - Giới hạn yêu cầu hàng tháng đã được sử dụng hết cho giai đoạn hiện tại.

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.

Đăng nhập để cấu hình khóa API