قائمة التحقق من الإعداد السريع
- افتح صفحة إدارة واجهة برمجة التطبيقات في لوحة التحكم الخاصة بك وأنشئ مفتاح API الشخصي الخاص بك.
- انسخ عنوان URL الأساسي الدقيق لواجهة برمجة تطبيقات المستخدم الموضح هناك، على سبيل المثال https://v1.tempmailg.com/api.
- أرسل كل طلب إلى مضيف API هذا مع Authorization: Bearer YOUR_USER_API_KEY و Accept: application/json.
- تتبع حصة الطلبات الشهرية الخاصة بك من نفس صفحة لوحة التحكم ومن رؤوس الحصة عندما تكون متاحة في استجابات واجهة برمجة التطبيقات للمستخدم. تُحسب فقط الطلبات الناجحة ذات الرمز 2xx ضمن الحصة.
الوصول إلى مفتاح API
سجّل الدخول لإنشاء مفتاح واجهة برمجة التطبيقات الشخصي ومشاهدة تفاصيل الحصص الحية.
تدفق المصادقة
- أنشئ مفتاح API الشخصي الخاص بك من صفحة إدارة واجهة برمجة التطبيقات في لوحة التحكم.
- أرسل المفتاح كرمز Bearer في كل طلب.
- استخدم عنوان URL الأساسي المخصص لواجهة برمجة تطبيقات المستخدم الموضح في صفحة إدارة واجهة برمجة التطبيقات الخاصة بك.
- أعد إنشاء المفتاح في أي وقت تريد فيه إبطال المفتاح القديم والبدء في استخدام مفتاح جديد فورًا.
الترويسات المطلوبة
Authorization: Bearer YOUR_USER_API_KEY
Accept: application/json
رؤوس حد المعدل والكمية
تصف رؤوس تحديد المعدل الميزانية المحددة للطلب. تُدرج رؤوس الحصة عندما تكون معلومات الحصة متاحة؛ لا تحسب رفضات الحد بالدقيقة حصتك الشهرية الكاملة.
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— الحد الأقصى للطلبات المسموح بها في الدقيقة (RPM) لخطةك.X-RateLimit-Remaining— الطلبات المتبقية في نافذة الدقيقة الحالية للـ RPM.X-RateLimit-Reset— الطابع الزمني Unix عندما يتم إعادة تعيين نافذة حد المعدل الدقيقة الحاليةX-Quota-Limit— السعة الإجمالية للرصيد الشهري والمشترى لحسابك.X-Quota-Remaining— الطلبات المتبقية المتاحة لواجهة برمجة التطبيقات في الشهر الحالي.X-Quota-Used— إجمالي طلبات API المستهلكة خلال فترة الفوترة الحالية.X-Quota-Reset— الطابع الزمني ISO-8601 عندما يتم إعادة تعيين حصتك الشهريةX-RateLimit-Scope— الميزانية الموصوفة بواسطة العناوين: account, ip, status_endpoint, أو mailbox.X-Mailbox-RateLimit-*— ميزانية منفصلة لإنشاء/تحديث صندوق البريد. تحافظ استجابات صندوق البريد الناجحة على RPM الحساب في X-RateLimit-*؛ رفض يقتصر على صندوق البريد يستخدم نطاق صندوق البريد ونافذة إعادة المحاولة الخاصة به.Retry-After— ثوانٍ حتى يصبح إعادة المحاولة المؤقتة مناسبة. قد يتطلب الخطة المعطلة أو الحصة المستنفذة تغيير الحساب بدلاً من ذلك، لذا قد لا يكون هذا الرأس موجودًا دائمًا.503 protection_unavailable— تخزين أو تنسيق حماية API غير متاح مؤقتًا. حاول مرة أخرى لاحقًا؛ هذا ليس فشلًا في الدفع أو خصمًا ائتمانيًا.
إدارة صندوق البريد
جلب النطاقات المسموح بها، إنشاء أو تبديل صناديق البريد، اختيار الفترات المسموح بها، وحذف العناوين المملوكة.
قائمة النطاقات المسموح بها
قائمة النطاقات المتاحة لإنشاء رسائل بريد إلكتروني مؤقتة. قم بالتصفية حسب النوع لرؤية النطاقات المجانية أو المميزة أو المخصصة المدعومة بخطة اشتراكك.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
type
|
query | string | اختياري |
مرشح مستوى النطاق. الإغفال يستخدم الكل عندما يكون الوصول إلى النطاق المميز مفعلاً، وإلا يكون مجانيًا. القيم المعترف بها: free, basic, pro, premium, custom, ultimate, 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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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
}
]
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.requested_type |
string | تم تطبيق مرشح النطاق. |
data.plan |
string | علامة الخطة الحالية. |
data.plan_name |
string | الاسم القابل للقراءة للخطة الحالية. |
data.allowed_types |
array<string> | مرشحات النطاق المتاحة لهذا الحساب. يمكن أن يظل مرشح معترف به محظورًا في خطتك. |
data.domains |
array | النطاقات القابلة للتحديد بعد التصفية؛ مصفوفة فارغة صالحة. |
data.domains[].domain |
string | اسم نطاق قابل للتحديد. |
data.domains[].type |
string | تسمية مستوى النطاق القابل للقراءة. |
data.domains[].custom |
boolean | ما إذا كان هذا نطاقًا مخصصًا. |
إنشاء صندوق بريد مؤقت
إنشاء صندوق بريد مؤقت مملوك. احذف اسم المستخدم والنطاق لتوليد عشوائي، أو قدم اسم مستخدم مخصص مسموح به ونطاقًا مسموحًا. يمكن لمعلمة الموفر اختيار توليد اسم مستعار Gmail أو Outlook.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
username
|
body | string | اختياري |
اسم مستخدم مخصص اختياري: من 2 إلى 64 حرف ASCII، أرقام، نقاط، شرطات سفلية أو شرطات. يتطلب إذن الخطة؛ يتم قبول custom_username أيضًا.
الافتراضي:
تم إنشاؤه عشوائيًا
|
domain
|
body | string | اختياري |
أحد النطاقات المسموح بها التي تم إرجاعها بواسطة GET /domains. الإغفال يختار نطاقًا مسموحًا به عشوائيًا.
الافتراضي:
نطاق مسموح عشوائي
|
lifetime
|
body | string | اختياري |
القيم المسموح بها:
10m — 10 دقيقة
1h — ساعة واحدة
2h — ساعتان
1d — يوم واحد
1w — أسبوع واحد
1m — 30 يومًا
3m — 90 يومًا
6m — 180 يومًا
1y — 365 يومًا
unlimited — غير محدود
الافتراضي:
العمر الافتراضي للخطة
|
provider
|
body | string | اختياري |
مزود صندوق البريد: standard، gmail_alias، أو outlook_alias.
الافتراضي:
standard
|
pin_enabled
|
body | boolean | اختياري |
حماية PIN اختيارية للبريد الجديد، عندما يسمح بها خطتك. لا تغير PIN للبريد الموجود.
الافتراضي:
false
|
pin
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة: PIN من 6 إلى 8 أرقام، يُرسل كسلسلة للحفاظ على الأصفار الأولية.
|
pin_confirmation
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة. يجب أن يتطابق تمامًا مع pin.
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
username (اسم مستخدم مخصص إذا سمحت الخطة.), domain (النطاق المسموح، على سبيل المثال example.com), lifetime (القيم المسموح بها: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited), provider (standard, gmail_alias, outlook_alias). احذف مدة الصلاحية، أو اتركها فارغة، لاستخدام مدة البريد الإلكتروني الافتراضية المُعَدة لخطةك الشهرية/السنوية الحالية. أرسل مدة صالحة مثل 1h لتجاوز هذا الإعداد الافتراضي. يُستخدم غير محدود فقط عندما يتم تكوينه كإعداد افتراضي للخطة أو عندما يُطلب صراحةً ويُسمح به. يتم أيضًا قبول معلمات الجسم mailbox_lifetime و email_lifetime؛ القيمة غير الفارغة الأولى هي الفائزة بهذا الترتيب: lifetime، mailbox_lifetime، email_lifetime. القيم غير الصالحة أو غير المسموح بها تُعيد HTTP 422 بدلاً من اختيار افتراضي بصمت.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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:17:58+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:17:58+00:00",
"email_token": "encrypted-email-token"
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.id |
integer | معرف صندوق البريد. تختلف المعرفات والعناوين والرموز المولدة لكل صندوق بريد. |
data.pin_protected |
boolean | ما إذا كان هذا صندوق البريد محميًا برمز PIN. لا يتم إرجاع أي PIN أو تجزئة PIN. |
data.email |
string | تم إنشاء عنوان صندوق البريد الكامل. |
data.domain |
string | نطاق صندوق البريد المُنشأ. |
data.provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
data.expire_at |
string|null | انتهاء فعال كطابع زمني ISO-8601، أو null لصندوق بريد غير محدود. |
data.expires_in_seconds |
number|null | ثوانٍ غير سالبة متبقية عند الحساب؛ الثواني الكسرية ممكنة. Null تعني غير محدودة، لا تعني صفر. |
data.mailbox_state |
string | حالة صندوق البريد الحالي: نشط، موقوف، منتهي الصلاحية، أو غير نشط. |
data.receiving_enabled |
boolean | ما إذا كان هذا صندوق البريد يقبل حاليًا الرسائل الواردة. |
data.message_count |
integer | عدد الرسائل الإجمالي المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.unread_message_count |
integer | عدد الرسائل غير المقروءة المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.last_message_received_at |
string|null | آخر وقت معروف للرسالة المستلمة بتنسيق ISO-8601، أو null عندما يكون غير متاح. |
data.message_count_synced_at |
string|null | آخر وقت مزامنة عدد الرسائل بتنسيق ISO-8601، أو null قبل المزامنة. |
data.created_at |
string|null | وقت إنشاء صندوق البريد بتنسيق ISO-8601. |
data.email_token |
string | مرجع صندوق بريد مشفر غير شفاف. لا يحل محل مصادقة Bearer أو فحوصات الملكية أو تفويض PIN. |
data.pin_grant |
object | شرطية: إنشاء صندوق بريد محمي برمز PIN نشط يُعيد هذا الإذن للقراءة؛ الإنشاء العادي غير المحمي يتجاهله. |
data.pin_grant.mailbox_id |
integer | معرّف صندوق البريد الذي يرتبط به منح القراءة الشرطي. |
data.pin_grant.unlock_token |
string | رمز قراءة غير شفاف لـ X-Mailbox-Unlock باستخدام بيانات اعتماد المالك نفسها. احتفظ به خاصًا وفي الذاكرة؛ إذ لا يخول منح القراءة حذفًا. |
data.pin_grant.scope |
string | النطاق المقروء لمنح الإنشاء الشرطي. |
data.pin_grant.idle_timeout_seconds |
integer | الوقت الخامل المسموح به لمنح القراءة، عادةً 3600 ثانية. |
data.pin_grant.absolute_timeout_seconds |
integer | الحد الأقصى لعمر صلاحية القراءة، عادةً 86400 ثانية. |
data.pin_grant.expires_at |
string | انتهاء صلاحية القراءة الحالية بتنسيق ISO-8601. |
data.pin_grant.absolute_expires_at |
string | انتهاء صلاحية منح القراءة المطلق بتنسيق ISO-8601. يمكن لتغييرات الأمان إلغاء المنحة في وقت أقرب. |
تحديث / تبديل صندوق البريد
إنشاء أو اختيار صندوق بريد بالاسم المستخدم والنطاق الجديد بعد التحقق من ملكية صندوق البريد الحالي. لا يؤدي ذلك إلى إعادة تسمية صندوق البريد القديم أو تغيير مدة صلاحيته في مكانه. عندما يختلف الوجهة، يبقى صندوق البريد القديم في السجل وقد يتم إيقافه بسبب حدود الصناديق النشطة. إعادة استخدام الوجهة النشطة الخاصة بك تعيد تطبيق مدة الصلاحية المطلوبة أو الإعداد الافتراضي للخطة.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
email
|
path | string | مطلوب |
العنوان البريدي الكامل الحالي لصندوق البريد المملوك للتبديل. URL-encode كل مقطع مسار؛ ترميز علامة الجمع كـ %2B.
|
username
|
path | string | مطلوب |
اسم المستخدم الجديد المطلوب: من 2 إلى 64 حرفًا أبجديًا رقميًا؛ يخضع لإذن اسم المستخدم المخصص.
|
domain
|
path | string | مطلوب |
اسم نطاق مسموح جديد.
|
lifetime
|
body | string | اختياري |
القيم المسموح بها:
10m — 10 دقيقة
1h — ساعة واحدة
2h — ساعتان
1d — يوم واحد
1w — أسبوع واحد
1m — 30 يومًا
3m — 90 يومًا
6m — 180 يومًا
1y — 365 يومًا
unlimited — غير محدود
الافتراضي:
العمر الافتراضي للخطة
|
pin_enabled
|
body | boolean | اختياري |
حماية PIN اختيارية للبريد الجديد، عندما يسمح بها خطتك. لا تغير PIN للبريد الموجود.
الافتراضي:
false
|
pin
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة: PIN من 6 إلى 8 أرقام، يُرسل كسلسلة للحفاظ على الأصفار الأولية.
|
pin_confirmation
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة. يجب أن يتطابق تمامًا مع pin.
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token للقراءة. أولاً أرسل POST للـ pin و scope=read إلى عنوان URL لفك القفل PIN. احتفظ بمصادقة Bearer العادية. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
lifetime (القيم المسموح بها: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). احذف مدة الصلاحية، أو اتركها فارغة، لاستخدام مدة البريد الإلكتروني الافتراضية المُعَدة لخطةك الشهرية/السنوية الحالية. أرسل مدة صالحة مثل 1h لتجاوز هذا الإعداد الافتراضي. يُستخدم غير محدود فقط عندما يتم تكوينه كإعداد افتراضي للخطة أو عندما يُطلب صراحةً ويُسمح به. يتم أيضًا قبول معلمات الجسم mailbox_lifetime و email_lifetime؛ القيمة غير الفارغة الأولى هي الفائزة بهذا الترتيب: lifetime، mailbox_lifetime، email_lifetime. القيم غير الصالحة أو غير المسموح بها تُعيد HTTP 422 بدلاً من اختيار افتراضي بصمت.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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:27:58+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:17:58+00:00",
"email_token": "encrypted-email-token"
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.id |
integer | معرف صندوق البريد. تختلف المعرفات والعناوين والرموز المولدة لكل صندوق بريد. |
data.pin_protected |
boolean | ما إذا كان هذا صندوق البريد محميًا برمز PIN. لا يتم إرجاع أي PIN أو تجزئة PIN. |
data.email |
string | تم إنشاء عنوان صندوق البريد الكامل. |
data.domain |
string | نطاق صندوق البريد المُنشأ. |
data.provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
data.expire_at |
string|null | انتهاء فعال كطابع زمني ISO-8601، أو null لصندوق بريد غير محدود. |
data.expires_in_seconds |
number|null | ثوانٍ غير سالبة متبقية عند الحساب؛ الثواني الكسرية ممكنة. Null تعني غير محدودة، لا تعني صفر. |
data.mailbox_state |
string | حالة صندوق البريد الحالي: نشط، موقوف، منتهي الصلاحية، أو غير نشط. |
data.receiving_enabled |
boolean | ما إذا كان هذا صندوق البريد يقبل حاليًا الرسائل الواردة. |
data.message_count |
integer | عدد الرسائل الإجمالي المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.unread_message_count |
integer | عدد الرسائل غير المقروءة المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.last_message_received_at |
string|null | آخر وقت معروف للرسالة المستلمة بتنسيق ISO-8601، أو null عندما يكون غير متاح. |
data.message_count_synced_at |
string|null | آخر وقت مزامنة عدد الرسائل بتنسيق ISO-8601، أو null قبل المزامنة. |
data.created_at |
string|null | وقت إنشاء صندوق البريد بتنسيق ISO-8601. |
data.email_token |
string | مرجع صندوق بريد مشفر غير شفاف. لا يحل محل مصادقة Bearer أو فحوصات الملكية أو تفويض PIN. |
data.pin_grant |
object | شرطية: إنشاء صندوق بريد محمي برمز PIN نشط يُعيد هذا الإذن للقراءة؛ الإنشاء العادي غير المحمي يتجاهله. |
data.pin_grant.mailbox_id |
integer | معرّف صندوق البريد الذي يرتبط به منح القراءة الشرطي. |
data.pin_grant.unlock_token |
string | رمز قراءة غير شفاف لـ X-Mailbox-Unlock باستخدام بيانات اعتماد المالك نفسها. احتفظ به خاصًا وفي الذاكرة؛ إذ لا يخول منح القراءة حذفًا. |
data.pin_grant.scope |
string | النطاق المقروء لمنح الإنشاء الشرطي. |
data.pin_grant.idle_timeout_seconds |
integer | الوقت الخامل المسموح به لمنح القراءة، عادةً 3600 ثانية. |
data.pin_grant.absolute_timeout_seconds |
integer | الحد الأقصى لعمر صلاحية القراءة، عادةً 86400 ثانية. |
data.pin_grant.expires_at |
string | انتهاء صلاحية القراءة الحالية بتنسيق ISO-8601. |
data.pin_grant.absolute_expires_at |
string | انتهاء صلاحية منح القراءة المطلق بتنسيق ISO-8601. يمكن لتغييرات الأمان إلغاء المنحة في وقت أقرب. |
حذف صندوق البريد
احذف صندوق بريد مملوك واستدعِ عملية تنظيف الرسائل والملفات الخاصة به. قد يتم حذف سجلات صندوق البريد المحتفظ بها بشكل ناعم داخليًا؛ لم يعد العنوان قابلًا للاستخدام عبر واجهة برمجة التطبيقات.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
email
|
path | string | مطلوب |
العنوان البريدي الكامل لصندوق البريد المملوك المراد حذفه. قم بترميز URL للعنوان؛ ترميز علامة الجمع كـ %2B.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token حذف لمرة واحدة. أولاً POST pin، scope=delete والإجراء/target_id الذي تم إرجاعه بواسطة استجابة 423 إلى PIN unlock URL. لا يمكن لرمز القراءة الحذف. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
200 OK • JSON{
"status": true,
"message": "Email has been successfully deleted."
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
message |
string | نتيجة الحذف. المورد المفقود يُعيد HTTP 404. |
Gmail & Outlook أسماء مستعارة
إنشاء صناديق بريد مستعارة ذات سمعة عالية على Gmail و Outlook/Hotmail.
إنشاء اسم مستعار Gmail
إنشاء صندوق بريد مؤقت جديد alias Gmail مملوك للمستخدم المصادق عليه.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
mode
|
body | string | اختياري |
وضع الإنشاء: auto، dot، plus، أو plus_dot. يقبل أيضًا gmail_alias_mode. إذا لم يُسمح باختيار النمط، يُستخدم auto.
الافتراضي:
auto
|
username
|
body | string | اختياري |
لاحقة اسم مستعار مخصصة اختيارية: من 2 إلى 32 حرفًا أو رقمًا ASCII، يتم تحويلها إلى أحرف صغيرة؛ تخضع لإذن الميزة. كما تقبل custom_username أو alias_username.
الافتراضي:
تم الإنشاء تلقائيًا
|
domain
|
body | string | اختياري |
استخدم عشوائيًا، gmail.com أو googlemail.com؛ يتم قبول alias_domain أيضًا. الإغفال أو عدم توفر إذن اختيار النطاق يستخدم عشوائيًا.
الافتراضي:
random
|
lifetime
|
body | string | اختياري |
القيم المسموح بها:
10m — 10 دقيقة
1h — ساعة واحدة
2h — ساعتان
1d — يوم واحد
1w — أسبوع واحد
1m — 30 يومًا
3m — 90 يومًا
6m — 180 يومًا
1y — 365 يومًا
unlimited — غير محدود
الافتراضي:
العمر الافتراضي للخطة
|
pin_enabled
|
body | boolean | اختياري |
حماية PIN اختيارية للبريد الجديد، عندما يسمح بها خطتك. لا تغير PIN للبريد الموجود.
الافتراضي:
false
|
pin
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة: PIN من 6 إلى 8 أرقام، يُرسل كسلسلة للحفاظ على الأصفار الأولية.
|
pin_confirmation
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة. يجب أن يتطابق تمامًا مع pin.
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
mode (auto, dot, plus, plus_dot), username (اسم مستخدم مستعار مخصص), domain (مثال: gmail.com, googlemail.com), lifetime (القيم المسموح بها: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). احذف مدة الصلاحية، أو اتركها فارغة، لاستخدام مدة البريد الإلكتروني الافتراضية المُعَدة لخطةك الشهرية/السنوية الحالية. أرسل مدة صالحة مثل 1h لتجاوز هذا الإعداد الافتراضي. يُستخدم غير محدود فقط عندما يتم تكوينه كإعداد افتراضي للخطة أو عندما يُطلب صراحةً ويُسمح به. يتم أيضًا قبول معلمات الجسم mailbox_lifetime و email_lifetime؛ القيمة غير الفارغة الأولى هي الفائزة بهذا الترتيب: lifetime، mailbox_lifetime، email_lifetime. القيم غير الصالحة أو غير المسموح بها تُعيد HTTP 422 بدلاً من اختيار افتراضي بصمت.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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:17:58+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:17:58+00:00",
"email_token": "encrypted-email-token"
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.id |
integer | معرف صندوق البريد. تختلف المعرفات والعناوين والرموز المولدة لكل صندوق بريد. |
data.pin_protected |
boolean | ما إذا كان هذا صندوق البريد محميًا برمز PIN. لا يتم إرجاع أي PIN أو تجزئة PIN. |
data.email |
string | تم إنشاء عنوان صندوق البريد الكامل. |
data.domain |
string | نطاق صندوق البريد المُنشأ. |
data.provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
data.expire_at |
string|null | انتهاء فعال كطابع زمني ISO-8601، أو null لصندوق بريد غير محدود. |
data.expires_in_seconds |
number|null | ثوانٍ غير سالبة متبقية عند الحساب؛ الثواني الكسرية ممكنة. Null تعني غير محدودة، لا تعني صفر. |
data.mailbox_state |
string | حالة صندوق البريد الحالي: نشط، موقوف، منتهي الصلاحية، أو غير نشط. |
data.receiving_enabled |
boolean | ما إذا كان هذا صندوق البريد يقبل حاليًا الرسائل الواردة. |
data.message_count |
integer | عدد الرسائل الإجمالي المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.unread_message_count |
integer | عدد الرسائل غير المقروءة المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.last_message_received_at |
string|null | آخر وقت معروف للرسالة المستلمة بتنسيق ISO-8601، أو null عندما يكون غير متاح. |
data.message_count_synced_at |
string|null | آخر وقت مزامنة عدد الرسائل بتنسيق ISO-8601، أو null قبل المزامنة. |
data.created_at |
string|null | وقت إنشاء صندوق البريد بتنسيق ISO-8601. |
data.email_token |
string | مرجع صندوق بريد مشفر غير شفاف. لا يحل محل مصادقة Bearer أو فحوصات الملكية أو تفويض PIN. |
data.pin_grant |
object | شرطية: إنشاء صندوق بريد محمي برمز PIN نشط يُعيد هذا الإذن للقراءة؛ الإنشاء العادي غير المحمي يتجاهله. |
data.pin_grant.mailbox_id |
integer | معرّف صندوق البريد الذي يرتبط به منح القراءة الشرطي. |
data.pin_grant.unlock_token |
string | رمز قراءة غير شفاف لـ X-Mailbox-Unlock باستخدام بيانات اعتماد المالك نفسها. احتفظ به خاصًا وفي الذاكرة؛ إذ لا يخول منح القراءة حذفًا. |
data.pin_grant.scope |
string | النطاق المقروء لمنح الإنشاء الشرطي. |
data.pin_grant.idle_timeout_seconds |
integer | الوقت الخامل المسموح به لمنح القراءة، عادةً 3600 ثانية. |
data.pin_grant.absolute_timeout_seconds |
integer | الحد الأقصى لعمر صلاحية القراءة، عادةً 86400 ثانية. |
data.pin_grant.expires_at |
string | انتهاء صلاحية القراءة الحالية بتنسيق ISO-8601. |
data.pin_grant.absolute_expires_at |
string | انتهاء صلاحية منح القراءة المطلق بتنسيق ISO-8601. يمكن لتغييرات الأمان إلغاء المنحة في وقت أقرب. |
نطاقات الأسماء المستعارة في Outlook
جلب نطاقات alias النشطة في Outlook/Hotmail المتاحة لإنشاء صندوق البريد.
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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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
}
]
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.domains |
array | نطاقات Outlook/Hotmail النشطة؛ مصفوفة فارغة صالحة. |
data.domains[].domain |
string | اسم النطاق المتاح. |
data.domains[].type |
string | تسمية موفر قابلة للقراءة. |
data.domains[].selectable |
boolean | ما إذا كان حسابك يمكنه اختيار هذا النطاق صراحةً. |
data.domains[].locked |
boolean | ما إذا كان اختيار النطاق الصريح مقفلًا لحسابك. |
data.domains[].disabled_reason |
string|null | سبب قفل اختيار النطاق، أو null عندما يكون قابلًا للاختيار. |
إنشاء اسم مستعار Outlook
إنشاء صندوق بريد مؤقت جديد لاسم مستعار Outlook / Hotmail مملوك للمستخدم المصادق عليه.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
domain
|
body | string | اختياري |
استخدم عشوائيًا أو نطاقًا من GET /outlook-alias/domains؛ يتم قبول outlook_alias_domain أيضًا. بدون إذن الاختيار، يُستخدم العشوائي.
الافتراضي:
نطاق متاح عشوائي
|
username
|
body | string | اختياري |
لاحقة اسم مستعار مخصصة اختيارية: من 2 إلى 32 حرفًا أو رقمًا ASCII، يتم تحويلها إلى أحرف صغيرة؛ تخضع لإذن الميزة. كما تقبل custom_username أو alias_username.
الافتراضي:
تم الإنشاء تلقائيًا
|
lifetime
|
body | string | اختياري |
القيم المسموح بها:
10m — 10 دقيقة
1h — ساعة واحدة
2h — ساعتان
1d — يوم واحد
1w — أسبوع واحد
1m — 30 يومًا
3m — 90 يومًا
6m — 180 يومًا
1y — 365 يومًا
unlimited — غير محدود
الافتراضي:
العمر الافتراضي للخطة
|
pin_enabled
|
body | boolean | اختياري |
حماية PIN اختيارية للبريد الجديد، عندما يسمح بها خطتك. لا تغير PIN للبريد الموجود.
الافتراضي:
false
|
pin
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة: PIN من 6 إلى 8 أرقام، يُرسل كسلسلة للحفاظ على الأصفار الأولية.
|
pin_confirmation
|
body | string | اختياري |
مطلوب عندما تكون pin_enabled صحيحة. يجب أن يتطابق تمامًا مع pin.
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
domain (مثال: outlook.com, hotmail.com), username (اسم مستخدم مستعار مخصص), lifetime (القيم المسموح بها: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). احذف مدة الصلاحية، أو اتركها فارغة، لاستخدام مدة البريد الإلكتروني الافتراضية المُعَدة لخطةك الشهرية/السنوية الحالية. أرسل مدة صالحة مثل 1h لتجاوز هذا الإعداد الافتراضي. يُستخدم غير محدود فقط عندما يتم تكوينه كإعداد افتراضي للخطة أو عندما يُطلب صراحةً ويُسمح به. يتم أيضًا قبول معلمات الجسم mailbox_lifetime و email_lifetime؛ القيمة غير الفارغة الأولى هي الفائزة بهذا الترتيب: lifetime، mailbox_lifetime، email_lifetime. القيم غير الصالحة أو غير المسموح بها تُعيد HTTP 422 بدلاً من اختيار افتراضي بصمت.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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:17:58+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:17:58+00:00",
"email_token": "encrypted-email-token"
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.id |
integer | معرف صندوق البريد. تختلف المعرفات والعناوين والرموز المولدة لكل صندوق بريد. |
data.pin_protected |
boolean | ما إذا كان هذا صندوق البريد محميًا برمز PIN. لا يتم إرجاع أي PIN أو تجزئة PIN. |
data.email |
string | تم إنشاء عنوان صندوق البريد الكامل. |
data.domain |
string | نطاق صندوق البريد المُنشأ. |
data.provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
data.expire_at |
string|null | انتهاء فعال كطابع زمني ISO-8601، أو null لصندوق بريد غير محدود. |
data.expires_in_seconds |
number|null | ثوانٍ غير سالبة متبقية عند الحساب؛ الثواني الكسرية ممكنة. Null تعني غير محدودة، لا تعني صفر. |
data.mailbox_state |
string | حالة صندوق البريد الحالي: نشط، موقوف، منتهي الصلاحية، أو غير نشط. |
data.receiving_enabled |
boolean | ما إذا كان هذا صندوق البريد يقبل حاليًا الرسائل الواردة. |
data.message_count |
integer | عدد الرسائل الإجمالي المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.unread_message_count |
integer | عدد الرسائل غير المقروءة المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
data.last_message_received_at |
string|null | آخر وقت معروف للرسالة المستلمة بتنسيق ISO-8601، أو null عندما يكون غير متاح. |
data.message_count_synced_at |
string|null | آخر وقت مزامنة عدد الرسائل بتنسيق ISO-8601، أو null قبل المزامنة. |
data.created_at |
string|null | وقت إنشاء صندوق البريد بتنسيق ISO-8601. |
data.email_token |
string | مرجع صندوق بريد مشفر غير شفاف. لا يحل محل مصادقة Bearer أو فحوصات الملكية أو تفويض PIN. |
data.pin_grant |
object | شرطية: إنشاء صندوق بريد محمي برمز PIN نشط يُعيد هذا الإذن للقراءة؛ الإنشاء العادي غير المحمي يتجاهله. |
data.pin_grant.mailbox_id |
integer | معرّف صندوق البريد الذي يرتبط به منح القراءة الشرطي. |
data.pin_grant.unlock_token |
string | رمز قراءة غير شفاف لـ X-Mailbox-Unlock باستخدام بيانات اعتماد المالك نفسها. احتفظ به خاصًا وفي الذاكرة؛ إذ لا يخول منح القراءة حذفًا. |
data.pin_grant.scope |
string | النطاق المقروء لمنح الإنشاء الشرطي. |
data.pin_grant.idle_timeout_seconds |
integer | الوقت الخامل المسموح به لمنح القراءة، عادةً 3600 ثانية. |
data.pin_grant.absolute_timeout_seconds |
integer | الحد الأقصى لعمر صلاحية القراءة، عادةً 86400 ثانية. |
data.pin_grant.expires_at |
string | انتهاء صلاحية القراءة الحالية بتنسيق ISO-8601. |
data.pin_grant.absolute_expires_at |
string | انتهاء صلاحية منح القراءة المطلق بتنسيق ISO-8601. يمكن لتغييرات الأمان إلغاء المنحة في وقت أقرب. |
الرسائل والمرفقات
جلب صناديق الوارد الواردة، قراءة الرسائل الكاملة بصيغة HTML/نص، وبث المرفقات.
قائمة رسائل صندوق البريد
استرجع ملخصات الرسائل المتاحة وبيانات تعريف صندوق البريد. تقوم عمليات فحص البريد الوارد القياسية بإرجاع دفعة حديثة من ما يصل إلى 25 رسالة؛ هذا ليس نقطة نهاية ذات تاريخ كامل مُصفَّحة. استخدم GET /messages/{messageId} للحصول على النص الكامل والمرفقات.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
email
|
query | string | مطلوب |
العنوان الكامل للبريد الإلكتروني لصندوق البريد المملوك لقراءة الرسائل منه. قم بترميز URL لقيمة الاستعلام؛ قم بترميز علامة الجمع كـ %2B.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token للقراءة. أولاً أرسل POST للـ pin و scope=read إلى عنوان URL لفك القفل PIN. احتفظ بمصادقة Bearer العادية. <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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:17:58",
"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:17:58+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:17:58+00:00",
"message_count_synced_at": "2026-11-19T02:17:58+00:00"
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
mailbox |
string | عنوان صندوق البريد الذي تم طلب رسائله. |
email_token |
string | مرجع صندوق بريد مشفر غير شفاف؛ لا يزال يتطلب المصادقة العادية. |
mailbox_provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
messages |
array | ملخصات الرسائل. صندوق الوارد الفارغ يُعيد مصفوفة فارغة؛ استرجع رسالة واحدة للحصول على محتواها ومرفقاتها. |
expire_at |
string|null | انتهاء فعال كطابع زمني ISO-8601، أو null لصندوق بريد غير محدود. |
expires_in_seconds |
number|null | ثوانٍ غير سالبة متبقية عند الحساب؛ الثواني الكسرية ممكنة. Null تعني غير محدودة، لا تعني صفر. |
mailbox_state |
string | حالة صندوق البريد الحالي: نشط، موقوف، منتهي الصلاحية، أو غير نشط. |
receiving_enabled |
boolean | ما إذا كان هذا صندوق البريد يقبل حاليًا الرسائل الواردة. |
message_count |
integer | عدد الرسائل الإجمالي المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
unread_message_count |
integer | عدد الرسائل غير المقروءة المعروف؛ يمكن أن يعكس آخر مزامنة لصندوق البريد. |
last_message_received_at |
string|null | آخر وقت معروف للرسالة المستلمة بتنسيق ISO-8601، أو null عندما يكون غير متاح. |
message_count_synced_at |
string|null | آخر وقت مزامنة عدد الرسائل بتنسيق ISO-8601، أو null قبل المزامنة. |
mailbox_limit.limit |
integer | حد صندوق البريد النشط لهذا المزود؛ -1 يعني غير محدود. |
mailbox_limit.limit_label |
string | تسمية العرض لحد صندوق البريد. |
mailbox_limit.active_count |
integer | عدد صناديق البريد النشطة لهذا المزود. |
mailbox_limit.paused_count |
integer | عدد صناديق البريد المتوقفة لهذا المزود. |
mailbox_limit.paused_mailboxes |
array<string> | العناوين متوقفة بسبب حد صندوق البريد. |
mailbox_limit.remaining |
integer | الفتحات المتبقية لصناديق البريد النشطة؛ -1 تعني غير محدودة. هذا ليس حصة طلبات API. |
mailbox_limit.remaining_label |
string | عرض تسمية للفتحات المتبقية في صندوق البريد. |
mailbox_limit.reached |
boolean | ما إذا تم الوصول إلى حد صناديق البريد النشطة. |
mailbox_limit.blocked |
boolean | ما إذا كان حد صندوق البريد النشط صفرًا. |
mailbox_limit.provider |
string|null | المزود الذي ينطبق عليه حد صندوق البريد. |
messages[].id |
string | معرف الرسالة غير الشفاف المستخدم في نقاط النهاية للرسالة الواحدة والحذف والمرفقات. |
messages[].is_seen |
boolean | ما إذا تم وضع علامة على الرسالة كمقروءة. |
messages[].subject |
string | موضوع الرسالة. |
messages[].from |
string | اسم العرض للمرسل أو العنوان. |
messages[].from_email |
string | عنوان بريد المرسل الإلكتروني. |
messages[].receivedAt |
string | وقت الاستلام في المنطقة الزمنية للتطبيق، بتنسيق YYYY-MM-DD HH:mm:ss. |
messages[].otp |
string|null | تم اكتشاف رمز الاستخدام مرة واحدة عندما يكون متاحًا ومسموحًا؛ وإلا null. |
messages[].otp_locked |
boolean | ما إذا كان رمز الاستخدام لمرة واحدة المكتشف مخفيًا بسبب أذونات الميزة. |
messages[].verification_link |
string|null | تم اكتشاف عنوان URL للتحقق عندما يكون متاحًا ومسموحًا؛ وإلا يكون فارغًا. |
messages[].verification_link_locked |
boolean | ما إذا كان رابط التحقق المكتشف مخفيًا بسبب أذونات الميزة. |
messages[].from_name |
string|null | حقل ملخص Outlook: اسم المرسل الأصلي. غير موجود في ملخصات Standard و Gmail. |
messages[].snippet |
string|null | حقل ملخص Outlook: معاينة الرسالة القصيرة. |
messages[].received_at |
string|null | حقل ملخص Outlook: وقت الاستلام بصيغة ISO-8601، عندما يكون معروفًا. |
messages[].has_attachments |
boolean | حقل ملخص Outlook: ما إذا كانت بيانات تعريف المرفق موجودة. يتم التحقق من توفر التنزيل بشكل منفصل. |
احصل على رسالة واحدة
استرجاع رسالة مملوكة باستخدام معرف الرسالة غير الشفاف الخاص بها. تُرجع صيغ النص وبيانات مرفقات التعريف. تعتمد حقول النص على صيغة الرسالة؛ يضيف Outlook حقولًا خاصة بالمزود المذكورة أدناه.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
messageId
|
path | string | مطلوب |
معرّف الرسالة الفريد الذي يُرجع في قائمة الرسائل.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token للقراءة. أولاً أرسل POST للـ pin و scope=read إلى عنوان URL لفك القفل PIN. احتفظ بمصادقة Bearer العادية. <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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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:17:58",
"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"
}
]
}
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
data.id |
string | معرف الرسالة غير الشفاف. |
data.is_seen |
boolean | حالة قراءة الرسالة. القراءة يمكن أن تضع علامة بأنها تمت رؤيتها؛ البيانات المخزنة مؤقتًا قد تعكس حالة سابقة. |
data.subject |
string | موضوع الرسالة. |
data.from |
string | اسم العرض للمرسل أو العنوان. |
data.from_email |
string | عنوان بريد المرسل الإلكتروني. |
data.to |
string | عنوان صندوق بريد المستلم. |
data.mailbox_provider |
string | مزود صندوق البريد: standard، gmail_alias، أو outlook_alias. |
data.receivedAt |
string | وقت الاستلام في المنطقة الزمنية للتطبيق، بتنسيق YYYY-MM-DD HH:mm:ss. |
data.html |
boolean | ما إذا كانت الرسالة تحتوي على جسم HTML. |
data.html_content |
string | نص HTML عندما يكون موجودًا. يمكن للرسائل القياسية بدون HTML حذف هذا الحقل. اعتبر محتوى الرسالة غير موثوق به. |
data.text_content |
string | نص الجسم عندما يكون موجودًا؛ قد تحتوي الرسائل القياسية على نص مُهَرَّب داخل عنصر pre أو قد تُهمل هذا الحقل. |
data.content |
string | المحتوى المفضل للعرض، عادةً HTML عندما يكون متاحًا. |
data.attachments |
array | بيانات مرفق التعريف، أو مصفوفة فارغة. تتطلب التنزيلات المصادقة العادية وتفويض رقم التعريف الشخصي المناسب. |
data.attachments[].name |
string | اسم الملف لتشفيره كعنوان URL كجزء مسار واحد عند التحميل. |
data.attachments[].size |
integer | حجم المرفق بالبايت. |
data.attachments[].url |
string | تمت إضافة عنوان URL لتنزيل API للمستخدم المصادق عليه إلى المرفقات مع اسم ملف. لا يضمن عنوان URL أن الملف المحلي متاح. |
data.attachments[].extension |
string | حقل بيانات تعريف قياسي/جيميل: امتداد الملف عند توفيره. |
data.attachments[].id |
string | حقل البيانات الوصفية في Outlook: معرف مرفق الموفر. |
data.attachments[].content_type |
string | حقل بيانات التعريف Outlook: نوع محتوى MIME. |
data.from_name |
string|null | حقل تفاصيل Outlook: اسم المرسل الأصلي. |
data.to_email |
string|null | حقل تفاصيل Outlook: عنوان المستلم الأصلي. |
data.received_at |
string|null | حقل تفاصيل Outlook: وقت الاستلام بصيغة ISO-8601. |
data.has_html |
boolean | حقل تفاصيل Outlook: ما إذا كان هناك جسم HTML. |
حذف الرسالة
حذف رسالة واحدة مملوكة.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
messageId
|
path | string | مطلوب |
سلسلة معرف الرسالة الفريدة لحذفها نهائيًا.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token حذف لمرة واحدة. أولاً POST pin، scope=delete والإجراء/target_id الذي تم إرجاعه بواسطة استجابة 423 إلى PIN unlock URL. لا يمكن لرمز القراءة الحذف. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | اختياري |
مطلوب لإنشاء أو حذف محمي برمز PIN: مفتاح ثابت يتراوح طوله بين 16 إلى 128 حرفًا. أعد إرسال الطلب نفسه باستخدام نفس المفتاح لتجنب العمل المكرر.
|
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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
200 OK • JSON{
"status": true,
"message": "Message was deleted successfully."
}
| حقل | النوع | الوصف |
|---|---|---|
status |
boolean | ما إذا نجحت العملية. |
message |
string | نتيجة الحذف. المورد المفقود يُعيد HTTP 404. |
تحميل المرفق
تنزيل مرفق من رسالة مملوكة.
| معامل | الموقع | النوع | حالة | الوصف |
|---|---|---|---|---|
messageId
|
path | string | مطلوب |
معرّف الرسالة التي تحتوي على الملف.
|
filename
|
path | string | مطلوب |
اسم الملف والامتداد للمرفق الذي سيتم تنزيله.
|
X-Mailbox-Unlock
|
header | string | اختياري |
العنوان، صناديق البريد المحمية فقط: استخدم unlock_token للقراءة. أولاً أرسل POST للـ pin و scope=read إلى عنوان URL لفك القفل PIN. احتفظ بمصادقة Bearer العادية. <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
| حقل | النوع | الوصف |
|---|---|---|
Content-Disposition |
header | الاستجابة الناجحة تقوم بتنزيل اسم الملف المطلوب. |
body |
binary | ملفات البايت عند النجاح، وليس JSON. الأخطاء تُعيد JSON مع حالة غير 2xx. |
حدود المعدل والحصص
راقب ميزانيات الطلبات في الوقت الفعلي، حدود المعدل، وحصص الحساب دون استهلاك الأرصدة.
حد المعدل والحصة
تحقق من حد المعدل الحالي وحالة الحصة دون استهلاك أي استخدام للواجهة البرمجية. هذه النقطة النهاية خالية من الحصة ولا تخصم رصيد الواجهة البرمجية الشهري (حد الحماية من الإساءة: 60 طلب/دقيقة).
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'
استجابة توضيحية باستخدام بيانات صناعية. تتفاوت المعرفات والعناوين والرموز والطوابع الزمنية وحدود الخطة وعددها. لا تتجاوز عينات فترات الصلاحية الإعداد الافتراضي لخطةك. توضح أوصاف حقول الاستجابة القابلة للفراغ والحقول الخاصة بالمزود.
مثال على الاستجابة
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"
}
}
}
| حقل | النوع | الوصف |
|---|---|---|
data.limit |
integer|string | حد طلبات الحساب في الدقيقة. السلسلة unlimited تشير إلى ميزانية دقيقة غير محدودة؛ هذا مستقل عن الحصة الشهرية. |
data.remaining |
integer|string | فتحات دقيقة الميزانية المتبقية في الحساب، أو السلسلة غير محدودة. القيمة الإيجابية لا تعني بقاء رصيد API. |
data.reset |
integer | ثوانٍ لإطار دقيقة الحساب، وليس لإعادة ضبط الحصة الشهرية. يمكن للميزانيات الدقيقة المعطلة أو غير المحدودة الاحتفاظ بقيمة اسمية قدرها 60 ثانية؛ هذا لا يضمن الوصول بعد الانتظار. |
data.plan |
string | علامة الخطة الحالية. يتم توفير اسم الخطة القابل للقراءة بشكل منفصل في data.quota.plan_name. |
data.quota.enabled |
boolean | ما إذا كان الوصول إلى واجهة برمجة التطبيقات العالمية وخطة/الائتمان مفعلاً. هذا لا يشير إلى السعة المتبقية ولا يحل محل مفتاح واجهة برمجة التطبيقات للمستخدم. |
data.quota.user_api_status |
boolean | ما إذا كان المستخدم قد فعل مفتاح واجهة برمجة التطبيقات الخاص به. تتطلب العمليات هذا المفتاح بالإضافة إلى الوصول المفعل والسعة المتاحة. |
data.quota.plan_name |
string | الاسم القابل للقراءة للخطة الحالية. |
data.quota.period |
string | فترة الاستخدام الشهرية في تنسيق YYYY-MM، باستخدام توقيت التطبيق؛ ليست بالضرورة فترة الفوترة للاشتراك. |
data.quota.base_limit |
integer | البدل الأساسي الشهري للخطة. القيمة -1 تعني غير محدود. |
data.quota.extra_requests |
integer | تم منح مخصص شهري إضافي لفترة الاستخدام الحالية; منفصل عن الأرصدة المشتراة. |
data.quota.monthly_limit |
integer | البدل الأساسي بالإضافة إلى طلبات إضافية للفترة الحالية. قيمة -1 تعني غير محدود. الائتمانات المشتراة غير مشمولة. |
data.quota.monthly_remaining |
integer|null | الحد الشهري المتبقي المحدود، أو null عندما يكون الحصة الشهرية غير محدودة. يجب عدم تفسير null كصفر. |
data.quota.used |
integer | عمليات API الناجحة التي تم احتسابها في فترة الاستخدام الحالية، بما في ذلك العمليات التي تستخدم الأرصدة. لا تزيد فحوصات الحالة من هذه القيمة. |
data.quota.purchased_credits |
integer | رصيد الائتمان الحالي، بما في ذلك رصيد المكافآت للخطة النشطة. يجب عدم إضافة رصيد المكافآت إلى هذا الرصيد مرة ثانية. |
data.quota.bonus_credits |
integer | الجزء النشط من رصيد الائتمان المتعلق بمكافأة الخطة؛ تفصيل للـ purchased_credits، وليس سعة إضافية. |
data.quota.direct_purchased_credits |
integer | رصيد الائتمان باستثناء جزء المكافأة النشط للخطة. هذه القيمة بالإضافة إلى bonus_credits تساوي purchased_credits. |
data.quota.remaining |
integer|null | الرصيد الشهري المتبقي بالإضافة إلى رصيد الائتمان الحالي، دون احتساب المكافآت مرتين. القيمة Null تعني حصة شهرية غير محدودة. لا تزال تصاريح الميزات الفردية والحدود الأخرى للطلبات سارية. |
data.quota.unlimited |
boolean | ما إذا كانت الحصة الشهرية غير محدودة. هذا لا يجعل ميزانية الدقائق للحساب أو حدود الميزات الأخرى غير محدودة. |
data.quota.usage_percent |
integer | نسبة مئوية مدورة متوافقة مع لوحة التحكم من 0 إلى 100: المستخدمة مقسومة على المستخدمة زائد المتبقية، مضروبة في 100. تشمل سعة الائتمان المتاحة، لذا يمكن لإعادة الشحن خفض النسبة. تكون 0 للحد غير المحدود أو مجموعة بحجم صفر؛ ليست نسبة الحد الدقيق للدقيقة ولا قرار وصول. |
data.quota.reset_at |
string | طابع زمني بتنسيق ISO-8601 مع إزاحة المنطقة الزمنية لإعادة ضبط حصة الشهر التقويمي التالي. هذا ليس تاريخ انتهاء الاشتراك، وإعادة الضبط الشهرية لا تعيد تعبئة الأرصدة المشتراة. |
status |
string | النجاح الحرفي لنقطة النهاية هذه. نقاط النهاية الأخرى للصناديق البريدية الناجحة تستخدم القيمة المنطقية true. |
data.monthly_limit |
integer | اسم مستعار للتوافق لحقل data.quota المقابل؛ لا تقم بإضافته مرة أخرى عند حساب الأرصدة. |
data.monthly_remaining |
integer|null | اسم مستعار للتوافق لحقل data.quota المقابل؛ لا تقم بإضافته مرة أخرى عند حساب الأرصدة. |
data.purchased_credits |
integer | اسم مستعار للتوافق لحقل data.quota المقابل؛ لا تقم بإضافته مرة أخرى عند حساب الأرصدة. |
ويب هوك صندوق البريد (دفع في الوقت الحقيقي)
بدلاً من استفسار تكراري للويب API (GET /messages) للتحقق من وصول البريد، قم بتكوين ووكبوكات لإرسال الرسائل الجديدة إلى خادمك أو تدفق عملك التلقائي في الوقت الحقيقي.
أحداث الويبوك المsupported
يمكن لكل webhook الاشتراك في نوع أو أكثر من أنواع الأحداث. يتلقى نقطة النهاية الخاصة بك إشعارًا بالحدث كلما تم تشغيل أحد هذه المشغلات.
يتم الإرسال في الوقت الفعلي كلما وصل رسالة جديدة إلى صندوق البريد المحدد.
يتم إرساله عندما تنتهي صلاحية صندوق البريد المؤقت ويتوقف معالجة webhook.
يتم إرساله عندما يصبح صندوق بريد منتهي الصلاحية نشطًا مرة أخرى وفقًا لقواعد الخطة.
تم الإرسال مباشرةً قبل حذف webhook وصندوق البريد الخاص به.
رُقَمُ الطَلَبِ وَالتَّصْدِيقُ بِالْهَمَاسِ
يحتوي كل تسليم لويب هوك على رؤوس أمن خاصة. استخدم رأس X-TempMailg-Signature للتحقق من أن طلبات الوصول تم إرسالها بشكل حقيقي من قبل TempMailg ولم يتم تعديله.
| اسم الرأس (العنوان) | مثال على قيمة | الوصف |
|---|---|---|
User-Agent |
TempMailg-Webhooks/1.0 | معرّف قياسي لعامل تسليم الويب هوك. |
X-TempMailg-Event |
email.received | نوع الحدث الذي أدى إلى هذه التسليم. |
X-TempMailg-Event-Id |
e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c | معرّف UUID فريد مخصص لهذه محاولة التسليم. |
X-TempMailg-Timestamp |
1725192000 | طابع زمني لحقبة يونكس يوضح متى تم بدء الطلب. |
X-TempMailg-Signature |
sha256=d7a8fbb307d7809469ca933b02d82941... | توقيع HMAC-SHA256 محسوب من {timestamp}.{raw_body} باستخدام سرك. |
X-TempMailg-Test |
false | صحيح عندما يتم إرساله عبر ميزة "Send Test Ping" في لوحة التحكم الخاصة بك. |
يتم حساب التوقيع باستخدام HMAC مع SHA256 على سلسلة النص التالية:
hash_hmac('sha256', "${X-TempMailg-Timestamp}.${raw_request_body}", your_webhook_secret)
مثال علىayload حدث (email.received)
تم تسليمه كتحميل تطبيق/json في جسم طلب HTTP POST.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:17:58+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:17:58+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"
}
}
أمثلة تنفيذ المستلم
اختر لغتك لرؤية كيفية استلام الويب هوكس والتحقق من توقيعات HMAC بأمان.
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]);
المنصات المدعومة وتكاملات الأتمتة
تعمل Webhooks TempMailg جاهزة للاستخدام مع نقاط النهاية HTTPS القياسية ومنصات الأتمتة/بدون كود الرائدة:
الأخطاء الشائعة واستكشاف الأخطاء وإصلاحها
هذه هي رموز الاستجابة الأكثر شيوعًا التي قد تراها أثناء دمج واجهة برمجة تطبيقات المستخدم.
رمز Bearer غير صالح أو مفقود أو تم إلغاؤه.
الملكية أو أذونات الميزة أو الوصول إلى النطاق أو حجم المرفق منع العملية. تحقق من رمز الاستجابة والرسالة.
لم يتم العثور على المورد على المضيف المسموح به أو لا يخص المستخدم.
تم إعادة استخدام مفتاح العملية مع تفاصيل مختلفة، أو عملية أخرى قيد الانتظار، أو تم تغيير أمان صندوق البريد. افحص الشيفرة قبل إعادة المحاولة.
صندوق البريد انتهت صلاحيته أو غير نشط.
معلمات غير صالحة، عمر غير مسموح به، سعة الاسم المستعار غير متاحة، إعداد PIN غير صالح أو مفتاح Idempotency-Key مفقود/غير صالح منع العملية.
يتطلب صندوق بريد محمي رمز X-Mailbox-Unlock صالح ومحدود النطاق. استخدم action و target_id من الاستجابة للحذف. يجب حل متطلبات القفل أو الاستعادة قبل إعادة المحاولة.
حد الطلب، الخطة المعطلة، الحصة المستنفذة، أو فترة الانتظار منعوا العملية. تحقق من السبب ورؤوس الميزانية المتاحة. Retry-After اختياري.
لم يتمكن الخادم من إكمال العملية. بالنسبة لإنشاء أو حذف محمي، احتفظ بنفس الطلب ومفتاح Idempotency-Key عند إعادة المحاولة.
تعذر التحقق من تخزين الحماية أو التنسيق. أعد المحاولة بعد التأخير المحدد. هذا الرد ليس دفعة فاشلة.
قائمة التحقق السريعة
- 401 Unauthorized - رمز Bearer مفقود أو خاطئ أو ملغى أو منسوخ بشكل غير صحيح.
- 403 Forbidden - الخطة الحالية لا تملك صلاحية الوصول إلى واجهة برمجة تطبيقات المستخدم حاليًا.
- 404 Not Found - المورد غير موجود أو هناك خطأ في المعلمة
- 410 Gone / Expired - البريد الإلكتروني انتهت صلاحيته أو لم يعد نشطًا.
- 429 Rate Limited - تحقق من سبب الاستجابة ورؤوس الميزانية. ينطبق Retry-After فقط على الحدود الزمنية؛ قد تتطلب الاعتمادات المستنفدة أو الوصول المعطل تغيير الحساب.
الخطوة التالية الموصى بها
إذا كنت مسجلاً للدخول، افتح إدارة واجهة برمجة التطبيقات أولاً وأكد من مفتاحك وحد الطلبات وخطط الوصول والحصول على عنوان قاعدة واجهة برمجة التطبيقات للمستخدم قبل تصحيح التطبيق الخارجي.