📧 TempMail API Documentation

Comprehensive guide to using the TempMail API

https://geniusgsm.com/tempmail

📋 Table of Contents

POST /api/create-temp-email/

Create a new temporary email and save it to the database

Request Body ()

{ "email_name": "optional_email_name" }

📥 Response

201 Created
✓ Success Response
{ "success": true, "email": "q83621vdqwz5@geniusgsm.com", "inbox_id": "550e8400-e29b-41d4-a716-446655440000", "created_at": "2026-04-08T10:30:45.123456Z" }

⚠️ Error Responses

400 Bad Request
{ "error": "No domains available" }
💡 Example cURL
curl -X POST https://geniusgsm.com/tempmail/api/create-temp-email/ \ -H "Content-Type: application/json" \ -d '{"email_name": "myusername"}'
GET /api/dovecot/mailbox/<username>/

Get all emails from a mailbox

📋 Parameters

Parameter Type Description Example
username string Username from email (without @geniusgsm.com) q83621vdqwz5

📥 Response

200 OK
✓ Success Response
{ "emails": [ { "filename": "message.eml", "from": "ghassan@example.com", "from_name": "Ghassan Mohammed", "to": "q83621vdqwz5@geniusgsm.com", "subject": "Hello User", "date": "2026-04-08T09:30:00Z", "size": 2048, "headers": { ... }, "body": "Email body content...", "attachments": [] } ], "total": 1 }
💡 Example cURL
curl -X GET https://geniusgsm.com/tempmail/api/dovecot/mailbox/q83621vdqwz5/
GET /api/dovecot/mailbox/<username>/<filename>/

Get a specific single message

📋 Parameters

Parameter Type Description
username string Username
filename string Message file name
💡 Example cURL
curl -X GET https://geniusgsm.com/tempmail/api/dovecot/mailbox/q83621vdqwz5/message.eml/
POST /api/dovecot/mailbox/<username>/<filename>/

Mark message as read

💡 Example cURL
curl -X POST https://geniusgsm.com/tempmail/api/dovecot/mailbox/q83621vdqwz5/message.eml/ \ -H "Content-Type: application/json" \ -d '{}'
DELETE /api/dovecot/mailbox/<username>/<filename>/delete/

Delete an email from mailbox

📥 Response

200 OK
✓ Success Response
{ "message": "Email deleted successfully" }
💡 Example cURL
curl -X DELETE https://geniusgsm.com/tempmail/api/dovecot/mailbox/q83621vdqwz5/message.eml/delete/

🐍 Python Example

import requests import json # Create a new temporary email response = requests.post( 'https://geniusgsm.com/tempmail/api/create-temp-email/', json={'email_name': 'myemail'} ) data = response.json() email = data['email'] username = data['email'].split('@')[0] print(f"Email: {email}") # # import time time.sleep(5) # # Get mailbox = requests.get( f'https://geniusgsm.com/tempmail/api/dovecot/mailbox/{username}/' ).json() for email_msg in mailbox.get('emails', []): print(f"From: {email_msg.get('from')}") print(f"Subject: {email_msg.get('subject')}") print(f"Body: {email_msg.get('body')}")

JavaScript/Node.js Example

// Create a new temporary email fetch('https://geniusgsm.com/tempmail/api/create-temp-email/', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ email_name: 'myemail' }) }) .then(r => r.json()) .then(data => { const email = data.email; const username = email.split('@')[0]; console.log('Email created:', email); // // setTimeout(() => { fetch(`https://geniusgsm.com/tempmail/api/dovecot/mailbox/${username}/`) .then(r => r.json()) .then(mailbox => { mailbox.emails.forEach(msg => { console.log('From:', msg.from); console.log('Subject:', msg.subject); console.log('Body:', msg.body); }); }); }, 5000); });

cURL Script Example

#!/bin/bash # # response=$(curl -s -X POST https://geniusgsm.com/tempmail/api/create-temp-email/ \ -H "Content-Type: application/json" \ -d '{"email_name": "bashuser"}') # Extract email and username email=$(echo $response | grep -o '"email":"[^"]*' | cut -d'"' -f4) username=$(echo $email | cut -d'@' -f1) echo "Email: $email" # # sleep 5 # # Get curl -s -X GET https://geniusgsm.com/tempmail/api/dovecot/mailbox/$username/ | jq '.emails'

✓ Important Information:
  • Email belongs to the geniusgsm.com domain only
  • Mailboxes are preserved in database forever
  • Messages automatically deleted after 90 days
  • No limits on the number of temporary mailboxes you can create
  • All APIs are open and do not require Authentication
✓ Performance Notes:
  • Incoming mail is received immediately when sent
  • Messages may take 1-5 seconds to appear in the API after reception
  • You can use Polling every 3 seconds to check for new messages
  • It is recommended to use Webhooks for instant notifications (coming soon)

For more information or to report an issue, please contact us

← Back to Home Go to TempMail →