TempMailg ۱۰. مستندات API

۱۵. از این مستندات برای تولید کلید API شخصی، اتصال به میزبان API کاربر اختصاصی، خواندن پیام‌های صندوق پستی، مدیریت صندوق‌های پستی متعلق به کاربر و ادغام Temp Mail در برنامه‌ها یا اتوماسیون‌های خود استفاده کنید.

۹. آدرس پایه API کاربر

۱۶. فرمت درخواست ۱۷. از کلید API خود فقط در سرصفحه Authorization Bearer استفاده کنید و آدرس‌های endpoint را تمیز نگه دارید.

وارد شوید تا کلید API را ایجاد کنید حساب ایجاد کنید

۲۱. فهرست تنظیم سریع

۲۲. صفحه مدیریت API داشبورد خود را باز کنید و کلید API شخصی خود را ایجاد کنید.
۲۳. URL پایه API کاربر را کپی کنید، به عنوان مثال https://v1.yourdomain.com/api.
۲۴. هر درخواست را به آن میزبان API با Authorization: Bearer YOUR_USER_API_KEY ۲۵. و Accept: application/json.
۱. ردیابی سهم درخواست ماهانه خود را از همان صفحه داشبورد و از سرصفحه سهمی که در هر پاسخ API کاربر بازگردانده می‌شود، انجام دهید. تنها درخواست‌های موفق ۲xx در محاسبه سهم لحاظ می‌شوند.

۲. اگر API ۴۰۴ را بازگرداند ۳. مطمئن شوید که میزبان اختصاصی API کاربر را به دقت همانطور که در صفحه مدیریت API شما نشان داده شده است، فراخوانی می‌کنید.

۲. دسترسی کلید API

وارد شوید تا کلید API شخصی خود را ایجاد کنید و جزئیات سهم زنده را مشاهده کنید.

ورود ثبت نام

۶. جریان احراز هویت

۷. کلید API شخصی خود را از صفحه مدیریت API در داشبورد تولید کنید.
۸. کلید را به عنوان یک توکن Bearer در هر درخواست ارسال کنید.
۹. از URL پایه اختصاصی API کاربر که در صفحه مدیریت API شما نشان داده شده است، استفاده کنید.
۱۰. کلید را در هر زمان که می‌خواهید کلید قدیمی را باطل کنید و بلافاصله از یک کلید جدید استفاده کنید، بازسازی کنید.

۱۱.可见性 کلید ۱۲. کلید API کاربر شما تا زمانی که آن را بازسازی یا لغو نکنید، در صفحه مدیریت API شما قابل مشاهده باقی می‌ماند.

۱۳. سرصفحه‌های مورد نیاز

Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json

۱۴. سرصفحه‌های سهمی که در هر پاسخ بازگردانده می‌شوند

۱۵. این مقادیر سهم فقط پس از پاسخ‌های موفق ۲xx افزایش می‌یابند.

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

۱۶. انتهای نقاط API کاربر

۱۷. هر انتهای نقطه زیر از همان URL پایه و همان توکن Bearer استفاده می‌کند. درخواست‌های Mailbox، پیام و پیوست علیه حساب کاربر احراز هویت شده بررسی می‌شوند.

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

دریافت دامنه‌های مجاز برای برنامه و حساب کاربر فعلی.

مقادیر نوع مجاز: free, premium, all. برنامه رایگان فقط می تواند از free. برنامه پرمیوم می تواند از free, premium, یا all.

دریافت دامنه‌های مجاز

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'

پاسخ نمونه

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

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

ایجاد یک صندوق پستی تصادفی جدید متعلق به کاربر احراز هویت شده.

ایجاد صندوق پستی تصادفی

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'

پاسخ نمونه

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

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

به روز رسانی یا تغییر یک صندوق پستی متعلق به کاربر موجود به یک نام کاربری جدید و دامنه مجاز.

استفاده از یک صندوق پستی متعلق به کاربر موجود با آدرس {email}.

به روز رسانی صندوق پستی متعلق به کاربر

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'

پاسخ نمونه

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

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

۲۵. یک صندوق پستی متعلق به خود را حذف کنید.

حذف صندوق پستی متعلق به کاربر

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'

پاسخ نمونه

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

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

فهرست پیام‌ها برای یک صندوق پستی متعلق به کاربر.

پارامتر查询 ایمیل باید متعلق به حساب کاربری احراز هویت شده باشد.

خواندن پیام‌های صندوق پستی

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'

پاسخ نمونه

{
    "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:37:07",
            "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}

خواندن یک پیام متعلق به کاربر.

خواندن یک پیام

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'

پاسخ نمونه

{
    "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:37:07",
        "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}

حذف یک پیام متعلق به کاربر

۱. حذف یک پیام

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'

پاسخ نمونه

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

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

۲. دانلود یک فایل پیوست از یک پیام متعلق به کاربر.

۳. این endpoint فایل را به صورت مستقیم دانلود می‌کند.

۴. دانلود یک فایل پیوست

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

۱۸. رفتار دانلود ۱۹. این انتهای نقطه فایل درخواستی را به جای یک بدنه JSON به صورت مستقیم بازمی‌گرداند.

۲۰. اشکالات رایج و رفع اشکال

۲۱. اینها کد‌های پاسخ رایج‌ترین هستند که ممکن است در حین یکپارچه‌سازی API کاربر ببینید.

401 ۵. توکن Bearer نامعتبر یا از دست رفته.

403 ۶. دسترسی API کاربر برای برنامه فعلی کاربر غیرفعال است.

404 ۷. منبع در میزبان مجاز یافت نشد یا متعلق به کاربر نیست.

410 ۸. صندوق پستی منقضی شده یا غیرفعال است.

422 ۹. اعتبار سنجی ناموفق بود یا صندوق پستی/دامنه درخواستی مجاز نیست.

429 ۱۰. سقف استفاده از API کاربر در ماه超过 شده است.

۲۲. چک لیست سریع

401 - ۲۳. توکن Bearer از دست رفته، اشتباه، لغو شده یا به درستی کپی نشده است.
403 - ۲۴. برنامه فعلی در حال حاضر حق دسترسی به API کاربر را ندارد.
404 - ۲۵. Mailbox، پیام یا پیوست متعلق به آن کاربر نیست یا میزبان اشتباه استفاده می‌شود.
410 - صندوق پستی منقضی شده یا دیگر فعال نیست.
429 - سهم درخواست ماهانه به طور کامل برای دوره فعلی استفاده شده است.

قدم بعدی توصیه شده

اگر وارد سیستم شده اید، ابتدا مدیریت API را باز کنید و کلید، سهم، وضعیت دسترسی برنامه و URL پایه API کاربر را قبل از اشکال زدایی برنامه خارجی خود تایید کنید.

وارد شوید تا کلید API را پیکربندی کنید