۱۴. مستندات API TempMail

REST API v1 و وب‌هوک‌ها

TempMailg مستندات API توسعه‌دهنده

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

احراز هویت توکن حامل وب‌هوک‌های زمان واقعی نام‌های مستعار Gmail و Outlook پاسخ‌های JSON
۹. آدرس پایه API کاربر HTTPS
۱۶. فرمت درخواست ۱۷. از کلید API خود فقط در سرصفحه Authorization Bearer استفاده کنید و آدرس‌های endpoint را تمیز نگه دارید.

مدیریت صندوق پستی

دریافت دامنه‌های مجاز، ایجاد یا تعویض صندوق‌های ایمیل، انتخاب طول عمرهای مجاز، و حذف آدرس‌های مالکیت‌شده.

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

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

فهرست دامنه‌های موجود برای ایجاد ایمیل‌های موقت. برای مشاهده فقط دامنه‌های رایگان، پرمیوم یا سفارشی که توسط طرح اشتراک شما پشتیبانی می‌شوند، بر اساس نوع فیلتر کنید.

پارامترها 1
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
type query string اختیاری
فیلتر سطح دامنه. حذف همه را استفاده می‌کند وقتی دسترسی دامنه‌پریمیوم فعال است، در غیر این صورت رایگان. مقادیر شناخته‌شده: free, basic, pro, premium, custom, ultimate, all
پیش‌فرض: وابسته به حساب
دریافت دامنه‌های مجاز
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
آیا این یک دامنه سفارشی است.
POST https://v1.tempmailg.com/api/emails
#

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

یک صندوق پست موقت متعلق به خود ایجاد کنید. برای تولید تصادفی، نام کاربری و دامنه را حذف کنید، یا یک نام کاربری سفارشی مجاز و یک دامنه مجاز را فراهم کنید. پارامتر provider می‌تواند تولید نام مستعار Gmail یا Outlook را انتخاب کند.

پارامترها 8
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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 را برمی‌گردانند.
ایجاد صندوق پست
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. تغییرات امنیتی می‌توانند اعطا را زودتر لغو کنند.
POST https://v1.tempmailg.com/api/emails/{email}/{username}/{domain}
#

به‌روزرسانی / تعویض صندوق پست

پس از تأیید مالکیت صندوق پست فعلی، یک صندوق پست در نام کاربری و دامنه جدید ایجاد یا انتخاب کنید. این کار نام صندوق پست قدیمی را تغییر نمی‌دهد و طول عمر آن را در محل تغییر نمی‌دهد. اگر مقصد متفاوت باشد، صندوق پست قدیمی در تاریخچه باقی می‌ماند و ممکن است توسط محدودیت‌های صندوق پست فعال متوقف شود. استفاده مجدد از مقصد فعال خود، طول عمر درخواست‌شده یا پیش‌فرض برنامه آن را دوباره اعمال می‌کند.

پارامترها 9
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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>
استفاده از یک صندوق پستی متعلق به کاربر موجود با آدرس {email}. پارامتر بدنه اختیاری: lifetime (مقادیر مجاز: 10m, 1h, 2h, 1d, 1w, 1m, 3m, 6m, 1y, unlimited). دورهٔ زمان را حذف کنید یا خالی بگذارید تا از دورهٔ زمان پیش‌فرض ایمیل که برای طرح ماهانه/سالانهٔ فعلی شما پیکربندی شده استفاده شود. یک دورهٔ زمان مجاز مانند 1h ارسال کنید تا آن پیش‌فرض را نادیده بگیرید. نامحدود فقط زمانی استفاده می‌شود که به‌عنوان پیش‌فرض طرح پیکربندی شده باشد یا صراحتاً درخواست و مجاز باشد. پارامترهای بدنه mailbox_lifetime و email_lifetime نیز پذیرفته می‌شوند؛ اولین مقدار غیر خالی به ترتیب زیر برتری دارد: lifetime, mailbox_lifetime, email_lifetime. مقادیر نامعتبر یا غیرمجاز، به‌جای انتخاب پیش‌فرض به‌صورت ساکت، HTTP 422 را برمی‌گردانند.
به روز رسانی صندوق پستی متعلق به کاربر
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. تغییرات امنیتی می‌توانند اعطا را زودتر لغو کنند.
DELETE https://v1.tempmailg.com/api/emails/{email}
#

حذف صندوق پستی

حذف یک صندوق پست متعلق به کاربر و فراخوانی پاک‌سازی پیام‌ها و فایل‌های آن. سوابق حفظ‌شدهٔ صندوق پست ممکن است به‌صورت نرم داخلی حذف شوند؛ آدرس دیگر از طریق API قابل استفاده نیست.

پارامترها 3
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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 لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
حذف صندوق پستی متعلق به کاربر
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 با اعتبار بالا.

POST https://v1.tempmailg.com/api/gmail-alias/emails
#

ایجاد نام مستعار Gmail

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

پارامترها 8
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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 لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
نیاز دارد که مجوز Gmail Alias API در طرح اشتراک شما فعال باشد یا از طریق بسته اعتبار API باز شود. پارامترهای اختیاری: 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 را برمی‌گردانند.
ایجاد صندوق ایمیل مستعار Gmail
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. تغییرات امنیتی می‌توانند اعطا را زودتر لغو کنند.
GET https://v1.tempmailg.com/api/outlook-alias/domains
#

دامنه‌های مستعار Outlook

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

نیاز به فعال‌سازی مجوز Outlook Alias API در برنامه اشتراک شما یا باز کردن آن از طریق بسته اعتبار API دارد. نشان می‌دهد که آیا انتخاب دامنه خاص در طرح شما باز شده است یا خیر.
دریافت دامنه‌های مستعار Outlook
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 وقتی قابل انتخاب است.
POST https://v1.tempmailg.com/api/outlook-alias/emails
#

ایجاد نام مستعار Outlook

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

پارامترها 7
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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 لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
نیاز به فعال‌سازی مجوز Outlook Alias API در برنامه اشتراک شما یا باز کردن آن از طریق بسته اعتبار API دارد. پارامترهای اختیاری: 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 را برمی‌گردانند.
ایجاد صندوق ایمیل نام مستعار Outlook
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 https://v1.tempmailg.com/api/messages?email={email}
#

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

دریافت خلاصه‌های پیام‌های موجود و متادیتای صندوق پستی. اسکن‌های استاندارد صندوق ورودی یک دستهٔ اخیر حداکثر تا ۲۵ پیام را برمی‌گردانند؛ این یک نقطهٔ انتهایی صفحه‌بندی‌شده برای تاریخچهٔ کامل نیست. از GET /messages/{messageId} برای دریافت متن کامل و پیوست‌ها استفاده کنید.

پارامترها 2
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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>
ایمیل باید به حساب شما تعلق داشته باشد. خلاصه‌های استاندارد و Gmail شامل فیلدهای OTP و verification-link هستند؛ Outlook همچنین شامل from_name، snippet، received_at و has_attachments می‌شود. همگام‌سازی و کش‌کردن توسط ارائه‌دهنده می‌تواند دریافت پیام‌ها و شمارش‌های جدید را به تأخیر بیندازد.
خواندن پیام‌های صندوق پستی
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: آیا متادیتای پیوست وجود دارد. قابلیت دانلود به‌صورت جداگانه بررسی می‌شود.
GET https://v1.tempmailg.com/api/messages/{messageId}
#

دریافت یک پیام

یک پیام متعلق به خود را با شناسه پیام نامشخص آن بازیابی کنید. قالب‌های بدنه و فراداده پیوست‌ها را برمی‌گرداند. فیلدهای بدنه بسته به قالب پیام متفاوت هستند؛ Outlook فیلدهای خاص ارائه‌دهنده را که در زیر فهرست شده‌اند، اضافه می‌کند.

پارامترها 2
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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>
خواندن یک پیام
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 وجود دارد.
DELETE https://v1.tempmailg.com/api/messages/{messageId}
#

حذف پیام

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

پارامترها 3
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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 لازم است: یک کلید ثابت با طول ۱۶ تا ۱۲۸ کاراکتر. درخواست یکسان را با همان کلید دوباره امتحان کنید تا از کار تکراری جلوگیری شود.
۱. حذف یک پیام
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 را برمی‌گرداند.
GET https://v1.tempmailg.com/api/messages/{messageId}/attachments/{filename}
#

دانلود پیوست

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

پارامترها 3
پارامتر موقعیت ۱۳. نوع وضعیت ۲۲. توضیحات
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>
موفقیت بایت‌های فایل را برمی‌گرداند، نه JSON. فایل‌های بزرگ‌حجم HTTP 403 برمی‌گردانند؛ فایل‌های محلی گمشده یا در دسترس نیستند HTTP 404 برمی‌گردانند. نام فایل را به‌عنوان یک بخش مسیر به‌صورت URL-encode کنید. فقط متادیتای پیوست تضمین‌کننده در دسترس بودن دانلود نیست.
۴. دانلود یک فایل پیوست
curl --request GET \
  --url 'https://v1.tempmailg.com/api/messages/ap94AWDg123ELQz07vrVB9dLXlbqZM5NGwYxOJKko8n6m1/attachments/file.txt' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_USER_API_KEY' \
  --output file.txt
۱۸. رفتار دانلود ۱۹. این انتهای نقطه فایل درخواستی را به جای یک بدنه JSON به صورت مستقیم بازمی‌گرداند.
فیلدهای پاسخ
فیلد ۱۳. نوع ۲۲. توضیحات
Content-Disposition header
پاسخ موفق، فایل درخواست‌شده را دانلود می‌کند.
body binary
در صورت موفقیت بایت‌های فایل، نه JSON. خطاها JSON را با وضعیت غیر 2xx برمی‌گردانند.

محدودیت‌های نرخ و سهمیه‌ها

بودجه‌های درخواست در زمان واقعی، محدودیت‌های نرخ و سهمیه‌های حساب را بدون مصرف اعتبار نظارت کنید.

GET https://v1.tempmailg.com/api/rate-limit
#

محدودیت نرخ و سهمیه

محدودیت نرخ فعلی و وضعیت سهمیه خود را بدون مصرف هیچ استفاده‌ای از API بررسی کنید. این نقطه انتهایی بدون سهمیه است و اعتبار ماهانه API را کم نمی‌کند (حد محافظت در برابر سوءاستفاده: 60 درخواست/دقیقه).

X-RateLimit-* بودجه درخواست نشان داده شده را توصیف می‌کند؛ X-Quota-* ظرفیت ماهانه و خریداری‌شده را وقتی در دسترس باشد توصیف می‌کند. X-Mailbox-RateLimit-* بودجه جداگانه ایجاد/به‌روزرسانی صندوق پستی را گزارش می‌دهد. رد فقط برای صندوق پستی از محدوده صندوق پستی و پنجرهٔ تلاش مجدد خود استفاده می‌کند. ردهای محدودیت دقیقه ممکن است اطلاعات سهمیه را حذف کنند. Retry-After فقط برای تلاش مجدد زمان‌دار گنجانده می‌شود؛ دسترسی غیرفعال ممکن است به تغییر حساب کاربری نیاز داشته باشد. در این پاسخ وضعیت موفق، data.limit، data.remaining و data.reset بودجه دقیقه‌ای حساب را توصیف می‌کنند، نه اعتبارهای قابل صرف. شیء data.quota مجوز ماهانه، موجودی اعتبار و استفاده را توصیف می‌کند. فیلدهای موجود data.monthly_limit، data.monthly_remaining و data.purchased_credits به عنوان نام‌های مستعار فیلدهای مربوط به quota باقی می‌مانند. یک بررسی وضعیت موفقیت‌آمیز، عملیات دیگری از API را مجاز نمی‌کند. عملیات‌ها همچنان به دسترسی فعال، سهمیه موجود و پذیرش از طریق تمام محدودیت‌های قابل اعمال نیاز دارند. تصویر لحظه‌ای سهمیه، ظرفیت رزرو شده توسط درخواست در حال پیشرفت را تضمین نمی‌کند.
وضعیت محدودیت نرخ را بررسی کنید
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 مربوطه؛ هنگام محاسبه مانده‌ها آن را دوباره اضافه نکنید.

حفاظت از پین صندوق پست

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

آیا کوکی ها را می پذیرید؟

ما از کوکی ها برای بهبود تجربه مرور شما استفاده می کنیم. با استفاده از این سایت، شما به سیاست کوکی ما رضایت می دهید.

خواندن کوکی‌ها