TempMailg وثائق واجهة برمجة التطبيقات

استخدم هذه الوثائق لتوليد مفتاح API الشخصي الخاص بك، وربط مضيف واجهة برمجة تطبيقات المستخدم المخصص، وقراءة رسائل صندوق البريد، وإدارة صناديق البريد المملوكة، ودمج Temp Mail في تطبيقاتك أو أتمتاتك الخاصة.

عنوان आधة واجهة برمجة التطبيقات للمستخدم

تنسيق الطلب استخدم مفتاح API الخاص بك فقط في ترويسة Authorization Bearer وحافظ على نظافة عناوين URL لنقاط النهاية.

سجّل الدخول لإنشاء مفتاح واجهة برمجة التطبيقات إنشاء حساب

قائمة التحقق من الإعداد السريع

افتح صفحة إدارة واجهة برمجة التطبيقات في لوحة التحكم الخاصة بك وأنشئ مفتاح API الشخصي الخاص بك.
انسخ عنوان URL الأساسي الدقيق لواجهة برمجة تطبيقات المستخدم الموضح هناك، على سبيل المثال https://v1.yourdomain.com/api.
أرسل كل طلب إلى مضيف API هذا مع Authorization: Bearer YOUR_USER_API_KEY و Accept: application/json.
تتبع حصة طلباتك الشهرية من نفس صفحة لوحة التحكم ومن ترويسات الحصة التي تعود في كل استجابة لواجهة برمجة تطبيقات المستخدم. تحتسب طلبات 2xx الناجحة فقط ضمن الحصة.

إذا كانت واجهة برمجة التطبيقات ترجع 404 تأكد من أنك تستدعي مضيف واجهة برمجة تطبيقات المستخدم المخصص تمامًا كما هو موضح في صفحة إدارة واجهة برمجة التطبيقات الخاصة بك.

الوصول إلى مفتاح API

سجّل الدخول لإنشاء مفتاح واجهة برمجة التطبيقات الشخصي ومشاهدة تفاصيل الحصص الحية.

تسجيل الدخول سجل

تدفق المصادقة

أنشئ مفتاح API الشخصي الخاص بك من صفحة إدارة واجهة برمجة التطبيقات في لوحة التحكم.
أرسل المفتاح كرمز Bearer في كل طلب.
استخدم عنوان URL الأساسي المخصص لواجهة برمجة تطبيقات المستخدم الموضح في صفحة إدارة واجهة برمجة التطبيقات الخاصة بك.
أعد إنشاء المفتاح في أي وقت تريد فيه إبطال المفتاح القديم والبدء في استخدام مفتاح جديد فورًا.

رؤية المفتاح يبقى مفتاح واجهة برمجة تطبيقات المستخدم الخاص بك مرئيًا داخل صفحة إدارة واجهة برمجة التطبيقات الخاصة بك حتى تقوم بإعادة إنشائه أو إلغائه.

الترويسات المطلوبة

Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json

ترويسات الحصة التي تعود في كل استجابة

تزداد قيم الحصة هذه فقط بعد الاستجابات الناجحة 2xx.

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

نقاط نهاية واجهة برمجة تطبيقات المستخدم

تستخدم كل نقطة نهاية أدناه نفس عنوان URL الأساسي ونفس رمز Bearer. يتم التحقق من طلبات صندوق البريد والرسائل والمرفقات مقابل حساب المستخدم المصادق عليه.

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:48+00:00",
        "expires_in_seconds": 600,
        "created_at": "2026-06-28T09:37:48+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:48+00:00",
        "expires_in_seconds": 600,
        "created_at": "2026-06-28T09:37:48+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:48",
            "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:48",
        "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}

تنزيل مرفق من رسالة مملوكة.

نقطة النهاية هذه تنزّل الملف مباشرة.

تنزيل مرفق

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.

الأخطاء الشائعة واستكشاف الأخطاء وإصلاحها

هذه هي رموز الاستجابة الأكثر شيوعًا التي قد تراها أثناء دمج واجهة برمجة تطبيقات المستخدم.

401 Bearer token غير صالح أو مفقود.

403 الوصول إلى واجهة برمجة تطبيقات المستخدم معطل لخطة المستخدم الحالية.

404 لم يتم العثور على المورد على المضيف المسموح به أو لا يخص المستخدم.

410 صندوق البريد انتهت صلاحيته أو غير نشط.

422 فشل التحقق من الصحة أو صندوق البريد/النطاق المطلوب غير مسموح به.

429 تم تجاوز حصة واجهة برمجة تطبيقات المستخدم الشهرية.

قائمة التحقق السريعة

401 - رمز Bearer مفقود أو خاطئ أو ملغى أو منسوخ بشكل غير صحيح.
403 - الخطة الحالية لا تملك صلاحية الوصول إلى واجهة برمجة تطبيقات المستخدم حاليًا.
404 - صندوق البريد أو الرسالة أو المرفق لا ينتمي إلى ذلك المستخدم أو يتم استخدام المضيف الخاطئ.
410 - البريد الإلكتروني انتهت صلاحيته أو لم يعد نشطًا.
429 - تم استخدام حد الطلبات الشهري بالكامل للفترة الحالية.

الخطوة التالية الموصى بها

إذا كنت مسجلاً للدخول، افتح إدارة واجهة برمجة التطبيقات أولاً وأكد من مفتاحك وحد الطلبات وخطط الوصول والحصول على عنوان قاعدة واجهة برمجة التطبيقات للمستخدم قبل تصحيح التطبيق الخارجي.

سجّل الدخول لتكوين مفتاح واجهة برمجة التطبيقات