۲۱. فهرست تنظیم سریع
- ۲۲. صفحه مدیریت API داشبورد خود را باز کنید و کلید API شخصی خود را ایجاد کنید.
- ۲۳. URL پایه API کاربر را کپی کنید، به عنوان مثال https://v1.tempmailg.com/api.
- ۲۴. هر درخواست را به آن میزبان API با Authorization: Bearer YOUR_USER_API_KEY ۲۵. و Accept: application/json.
- سهمیه درخواست ماهانه خود را از همان صفحه داشبورد و از سرآیندهای سهمیه هنگام در دسترس بودن در پاسخهای API کاربر پیگیری کنید. فقط درخواستهای موفق 2xx در محاسبه سهمیه لحاظ میشوند.
۶. جریان احراز هویت
- ۷. کلید API شخصی خود را از صفحه مدیریت API در داشبورد تولید کنید.
- ۸. کلید را به عنوان یک توکن Bearer در هر درخواست ارسال کنید.
- ۹. از URL پایه اختصاصی API کاربر که در صفحه مدیریت API شما نشان داده شده است، استفاده کنید.
- ۱۰. کلید را در هر زمان که میخواهید کلید قدیمی را باطل کنید و بلافاصله از یک کلید جدید استفاده کنید، بازسازی کنید.
۱۳. سرصفحههای مورد نیاز
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— زمانسنج یونیکس زمانی که پنجره محدودیت نرخ دقیقه جاری بازنشانی میشود.X-Quota-Limit— کل ظرفیت اعتبار ماهانه و خریداریشده برای حساب شما.X-Quota-Remaining— درخواستهای API باقیمانده در ماه جاری.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 | آیا این یک دامنه سفارشی است. |
ایجاد صندوق پست موقت
یک صندوق پست موقت متعلق به خود ایجاد کنید. برای تولید تصادفی، نام کاربری و دامنه را حذف کنید، یا یک نام کاربری سفارشی مجاز و یک دامنه مجاز را فراهم کنید. پارامتر provider میتواند تولید نام مستعار Gmail یا Outlook را انتخاب کند.
| پارامتر | موقعیت | ۱۳. نوع | وضعیت | ۲۲. توضیحات |
|---|---|---|---|---|
username
|
body | string | اختیاری |
نام کاربری سفارشی اختیاری: ۲ تا ۶۴ حرف ASCII، رقم، نقطه، زیرخط یا خط تیره. نیاز به مجوز طرح دارد؛ custom_username نیز پذیرفته میشود.
پیشفرض:
بهصورت تصادفی تولید شده
|
domain
|
body | string | اختیاری |
یکی از دامنههای مجاز که توسط GET /domains برگردانده میشود. حذف یک دامنه مجاز تصادفی را انتخاب میکند.
پیشفرض:
دامنه مجاز تصادفی
|
lifetime
|
body | string | اختیاری |
مقادیر مجاز:
10m — ۱۰ دقیقه
1h — یک ساعت
2h — ۲ ساعت
1d — یک روز
1w — یک هفته
1m — ۳۰ روز
3m — ۹۰ روز
6m — ۱۸۰ روز
1y — ۳۶۵ روز
unlimited — نامحدود
پیشفرض:
طول عمر پیشفرض طرح
|
provider
|
body | string | اختیاری |
ارائهدهنده صندوق پستی: standard، gmail_alias یا outlook_alias.
پیشفرض:
standard
|
pin_enabled
|
body | boolean | اختیاری |
حفاظت اختیاری با PIN برای صندوق پستی جدید، هنگامی که برنامه شما اجازه دهد. این کار PIN صندوق پستی موجود را تغییر نمیدهد.
پیشفرض:
false
|
pin
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، لازم است: یک PIN شامل ۶ تا ۸ رقم، به صورت رشتهای ارسال شود تا صفرهای پیشرو حفظ شوند.
|
pin_confirmation
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، الزامی است. باید دقیقاً با pin مطابقت داشته باشد.
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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:45+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:45+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 — ۱۰ دقیقه
1h — یک ساعت
2h — ۲ ساعت
1d — یک روز
1w — یک هفته
1m — ۳۰ روز
3m — ۹۰ روز
6m — ۱۸۰ روز
1y — ۳۶۵ روز
unlimited — نامحدود
پیشفرض:
طول عمر پیشفرض طرح
|
pin_enabled
|
body | boolean | اختیاری |
حفاظت اختیاری با PIN برای صندوق پستی جدید، هنگامی که برنامه شما اجازه دهد. این کار PIN صندوق پستی موجود را تغییر نمیدهد.
پیشفرض:
false
|
pin
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، لازم است: یک PIN شامل ۶ تا ۸ رقم، به صورت رشتهای ارسال شود تا صفرهای پیشرو حفظ شوند.
|
pin_confirmation
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، الزامی است. باید دقیقاً با pin مطابقت داشته باشد.
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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:45+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:45+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. تغییرات امنیتی میتوانند اعطا را زودتر لغو کنند. |
حذف صندوق پستی
حذف یک صندوق پست متعلق به کاربر و فراخوانی پاکسازی پیامها و فایلهای آن. سوابق حفظشدهٔ صندوق پست ممکن است بهصورت نرم داخلی حذف شوند؛ آدرس دیگر از طریق API قابل استفاده نیست.
| پارامتر | موقعیت | ۱۳. نوع | وضعیت | ۲۲. توضیحات |
|---|---|---|---|---|
email
|
path | string | الزامی |
آدرس ایمیل کامل صندوقپستی مالک برای حذف. آدرس را بهصورت URL-encode کنید؛ علامت بهعلاوه را به %2B تبدیل کنید.
|
X-Mailbox-Unlock
|
header | string | اختیاری |
سرصفحه، فقط صندوقهای پست محافظتشده: از توکن بازکردن حذف یکبار مصرف استفاده کنید. ابتدا POST pin، scope=delete و action/target_id که توسط پاسخ 423 به PIN unlock URL برگردانده میشود. یک توکن خواندن نمیتواند حذف کند. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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
یک صندوق پست موقت جدید با نام مستعار Gmail که متعلق به کاربر احراز هویت شده است، ایجاد کنید.
| پارامتر | موقعیت | ۱۳. نوع | وضعیت | ۲۲. توضیحات |
|---|---|---|---|---|
mode
|
body | string | اختیاری |
حالت تولید: auto، dot، plus یا plus_dot. همچنین gmail_alias_mode را میپذیرد. اگر انتخاب سبک مجاز نباشد، auto استفاده میشود.
پیشفرض:
auto
|
username
|
body | string | اختیاری |
پسوند مستعار سفارشی اختیاری: ۲ تا ۳۲ حرف یا رقم ASCII، به حروف کوچک نرمالسازی میشود؛ تحت مجوز ویژگی. همچنین custom_username یا alias_username را میپذیرد.
پیشفرض:
تولید خودکار
|
domain
|
body | string | اختیاری |
از تصادفی، gmail.com یا googlemail.com استفاده کنید؛ alias_domain نیز پذیرفته میشود. حذف یا عدم دسترسی به انتخاب دامنه، از تصادفی استفاده میکند.
پیشفرض:
random
|
lifetime
|
body | string | اختیاری |
مقادیر مجاز:
10m — ۱۰ دقیقه
1h — یک ساعت
2h — ۲ ساعت
1d — یک روز
1w — یک هفته
1m — ۳۰ روز
3m — ۹۰ روز
6m — ۱۸۰ روز
1y — ۳۶۵ روز
unlimited — نامحدود
پیشفرض:
طول عمر پیشفرض طرح
|
pin_enabled
|
body | boolean | اختیاری |
حفاظت اختیاری با PIN برای صندوق پستی جدید، هنگامی که برنامه شما اجازه دهد. این کار PIN صندوق پستی موجود را تغییر نمیدهد.
پیشفرض:
false
|
pin
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، لازم است: یک PIN شامل ۶ تا ۸ رقم، به صورت رشتهای ارسال شود تا صفرهای پیشرو حفظ شوند.
|
pin_confirmation
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، الزامی است. باید دقیقاً با pin مطابقت داشته باشد.
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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:45+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:45+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
دریافت دامنههای مستعار فعال 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 | اختیاری |
پسوند مستعار سفارشی اختیاری: ۲ تا ۳۲ حرف یا رقم ASCII، به حروف کوچک نرمالسازی میشود؛ تحت مجوز ویژگی. همچنین custom_username یا alias_username را میپذیرد.
پیشفرض:
تولید خودکار
|
lifetime
|
body | string | اختیاری |
مقادیر مجاز:
10m — ۱۰ دقیقه
1h — یک ساعت
2h — ۲ ساعت
1d — یک روز
1w — یک هفته
1m — ۳۰ روز
3m — ۹۰ روز
6m — ۱۸۰ روز
1y — ۳۶۵ روز
unlimited — نامحدود
پیشفرض:
طول عمر پیشفرض طرح
|
pin_enabled
|
body | boolean | اختیاری |
حفاظت اختیاری با PIN برای صندوق پستی جدید، هنگامی که برنامه شما اجازه دهد. این کار PIN صندوق پستی موجود را تغییر نمیدهد.
پیشفرض:
false
|
pin
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، لازم است: یک PIN شامل ۶ تا ۸ رقم، به صورت رشتهای ارسال شود تا صفرهای پیشرو حفظ شوند.
|
pin_confirmation
|
body | string | اختیاری |
در صورتی که pin_enabled برابر true باشد، الزامی است. باید دقیقاً با pin مطابقت داشته باشد.
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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:45+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:45+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/متن، و پخش پیوستها.
فهرست پیامهای صندوقپستی
دریافت خلاصههای پیامهای موجود و متادیتای صندوق پستی. اسکنهای استاندارد صندوق ورودی یک دستهٔ اخیر حداکثر تا ۲۵ پیام را برمیگردانند؛ این یک نقطهٔ انتهایی صفحهبندیشده برای تاریخچهٔ کامل نیست. از GET /messages/{messageId} برای دریافت متن کامل و پیوستها استفاده کنید.
| پارامتر | موقعیت | ۱۳. نوع | وضعیت | ۲۲. توضیحات |
|---|---|---|---|---|
email
|
query | string | الزامی |
آدرس کامل ایمیل صندوق پستی متعلق به شما برای خواندن پیامها. مقدار جستجو را به صورت URL‑encode کنید؛ علامت بهعلاوه را به %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:45",
"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:45+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:45+00:00",
"message_count_synced_at": "2026-11-19T02:17:45+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 تأیید شناسایی شده وقتی در دسترس و مجاز باشد؛ در غیر این صورت null. |
messages[].verification_link_locked |
boolean | آیا لینک تأیید شناسایی شده توسط مجوزهای ویژگی مخفی شده است. |
messages[].from_name |
string|null | فیلد خلاصه Outlook: نام فرستنده اصلی. در خلاصههای استاندارد و 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:45",
"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 | متن اصلی وقتی موجود باشد؛ پیامهای استاندارد ممکن است متن escaped را در یک عنصر pre داشته باشند یا این فیلد را حذف کنند. |
data.content |
string | بدنهٔ ترجیحی برای نمایش، معمولاً HTML وقتی در دسترس باشد. |
data.attachments |
array | متادیتای پیوست، یا یک آرایه خالی. دانلودها نیاز به احراز هویت معمولی و مجوز PIN قابل اعمال دارند. |
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 | اختیاری |
سرصفحه، فقط صندوقهای پست محافظتشده: از توکن بازکردن حذف یکبار مصرف استفاده کنید. ابتدا POST pin، scope=delete و action/target_id که توسط پاسخ 423 به PIN unlock URL برگردانده میشود. یک توکن خواندن نمیتواند حذف کند. <code>https://v1.tempmailg.com/api/mailboxes/{mailbox}/pin/unlock</code>
|
Idempotency-Key
|
header | string | اختیاری |
برای ایجاد یا حذف محافظتشده با PIN لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
|
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 برمیگردانند. |
محدودیتهای نرخ و سهمیهها
بودجههای درخواست در زمان واقعی، محدودیتهای نرخ و سهمیههای حساب را بدون مصرف اعتبار نظارت کنید.
محدودیت نرخ و سهمیه
محدودیت نرخ فعلی و وضعیت سهمیه خود را بدون مصرف هیچ استفادهای از API بررسی کنید. این نقطه انتهایی بدون سهمیه است و اعتبار ماهانه API را کم نمیکند (حد محافظت در برابر سوءاستفاده: 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 | اسلاتهای دقیقهای باقیمانده حساب، یا رشته unlimited. مقدار مثبت به این معنی نیست که اعتبارهای API باقی ماندهاند. |
data.reset |
integer | ثانیهها برای بازه دقیقه حساب، نه بازنشانی سهم ماهانه. بودجههای دقیقه غیرفعال یا نامحدود میتوانند مقدار اسمی 60 ثانیه را حفظ کنند؛ این تضمین نمیکند که پس از انتظار دسترسی داشته باشید. |
data.plan |
string | برچسب طرح فعلی. نام قابل خواندن طرح بهصورت جداگانه در data.quota.plan_name ارائه میشود. |
data.quota.enabled |
boolean | اینکه آیا دسترسی API سراسری و plan/credit فعال است. این نشانگر ظرفیت باقیمانده نیست و جایگزین سوئیچ API کاربر نمیشود. |
data.quota.user_api_status |
boolean | آیا کاربر سوئیچ API کاربری خود را فعال کرده است. عملیات به این سوئیچ بههمراه دسترسی فعال و ظرفیت موجود نیاز دارند. |
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 | درصد گرد شده سازگار با داشبورد از ۰ تا ۱۰۰: استفاده تقسیم بر (استفاده بهعلاوه باقیمانده)، سپس در ۱۰۰ ضرب میشود. این شامل ظرفیت اعتبار موجود است، بنابراین شارژ مجدد میتواند درصد را کاهش دهد. برای سهمیه نامحدود یا استخر با اندازه صفر مقدار ۰ است؛ این درصد نرخ محدودیت دقیقهای یا تصمیم دسترسی نیست. |
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 REST (GET /messages) مراجعه کنید تا ایمیلهای دریافتی را بررسی کنید، وبهوکها را پیکربندی کنید تا پیامهای جدید را به صورت زمانحالی به سرور یا فرآیند خودتوماتیک شما ارسال کنند.
رویدادهای وبهوک پشتیبانیشده
هر وبهوک میتواند به یک یا چند نوع رویداد مشترک شود. آدرسنامهٔ شما یک اطلاعرسانی رویداد دریافت میکند هر بار که یکی از این رویدادها فعال میشود.
بهصورت زمان واقعی ارسال میشود هر زمان که پیام جدیدی به صندوق پستی انتخابشده برسد.
هنگامی که صندوق پستی موقت منقضی میشود و پردازش وبهوک متوقف میشود، ارسال میگردد.
ارسال میشود هنگامی که صندوق پستی منقضی شده دوباره تحت قوانین برنامه فعال میشود.
ارسال شده درست قبل از حذف وبهوک و صندوق پستی آن.
سربرگهای درخواست و تأیید امضا HMAC
هر ارسال وبهوک حاوی سربرگهای امنیتی ویژه است. از سربرگ 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 | مهر زمان یونیکس (Unix epoch) که نشان میدهد درخواست چه زمانی آغاز شد. |
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)
نمونه داده رویداد (email.received)
به عنوان application/json در بدنه درخواست HTTP POST ارسال میشود.
{
"id": "e7b1a2c3-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
"version": "1.0",
"event": "email.received",
"occurred_at": "2026-11-19T02:17:46+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:46+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]);
پلتفرمهای پشتیبانیشده و ادغامهای خودکار
وبهوکهای TempMailg بهصورت آماده با نقاط انتهایی استاندارد HTTPS و پلتفرمهای پیشرو بدون کد/اتوماتیک کار میکنند:
۲۰. اشکالات رایج و رفع اشکال
۲۱. اینها کدهای پاسخ رایجترین هستند که ممکن است در حین یکپارچهسازی API کاربر ببینید.
توکن Bearer نامعتبر، گمشده یا لغو شده.
مالکیت، مجوزهای ویژگی، دسترسی به دامنه یا اندازه پیوست مانع عملیات شد. کد پاسخ و پیام را بررسی کنید.
۷. منبع در میزبان مجاز یافت نشد یا متعلق به کاربر نیست.
کلید عملیات با جزئیات متفاوت دوباره استفاده شد، عملیات دیگری در انتظار است یا امنیت صندوق پستی تغییر کرده است. قبل از تلاش مجدد کد را بررسی کنید.
۸. صندوق پستی منقضی شده یا غیرفعال است.
پارامترهای نامعتبر، زمانسنجی غیرمجاز، ظرفیت مستعار در دسترس نیست، تنظیم PIN نامعتبر یا عدم وجود/نامعتبر بودن Idempotency-Key باعث جلوگیری از عملیات شد.
یک صندوق پستی محافظتشده به یک توکن معتبر scoped X-Mailbox-Unlock نیاز دارد. برای حذف، از action و target_id موجود در پاسخ استفاده کنید. پیشنیازهای قفلگذاری یا بازیابی باید پیش از تلاش مجدد برطرف شوند.
یک محدودیت درخواست، طرح غیرفعال، سهمیه تمامشده یا زمان انتظار مانع عملیات شد. دلیل و سرآیندهای بودجه در دسترس را بررسی کنید. Retry-After اختیاری است.
سرور نتوانست عملیات را تکمیل کند. برای ایجاد یا حذف محافظتشده، هنگام تلاش مجدد همان درخواست و Idempotency-Key را حفظ کنید.
ذخیرهسازی حفاظت یا هماهنگی قابل تأیید نبود. پس از تأخیر مشخص شده دوباره تلاش کنید. این پاسخ یک پرداخت ناموفق نیست.
۲۲. چک لیست سریع
- 401 Unauthorized - ۲۳. توکن Bearer از دست رفته، اشتباه، لغو شده یا به درستی کپی نشده است.
- 403 Forbidden - ۲۴. برنامه فعلی در حال حاضر حق دسترسی به API کاربر را ندارد.
- 404 Not Found - مورد مورد نظر یافت نشد یا پارامتر نامعتبر است
- 410 Gone / Expired - صندوق پستی منقضی شده یا دیگر فعال نیست.
- 429 Rate Limited - دلیل پاسخ و هدرهای بودجه را بررسی کنید. مقدار Retry-After فقط برای محدودیتهای زمانی اعمال میشود؛ اعتبارهای تمامشده یا دسترسی غیرفعال ممکن است نیاز به تغییر حساب داشته باشند.
قدم بعدی توصیه شده
اگر وارد سیستم شده اید، ابتدا مدیریت API را باز کنید و کلید، سهم، وضعیت دسترسی برنامه و URL پایه API کاربر را قبل از اشکال زدایی برنامه خارجی خود تایید کنید.