API Documentation
Complete reference for the MailGen REST API โ mail reading, account checking, and token management tools.
Quick Reference
Authentication
MailGen API is public โ no API key or token is required. All endpoints are protected by IP-based rate limiting.
Rate Limiting
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per minute (300) |
X-RateLimit-Remaining | Remaining requests in current window |
When the limit is exceeded, the API returns HTTP 429:
429 Response
{
"success": false,
"error": "Rate limit exceeded. Try again in 34 seconds.",
"retry_after": 34
}1. Live Check
POST/api/live-check
Check if a Hotmail/Outlook account is live and active.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
emailData | string | โ Yes | Account: email|password|refresh_token|client_id |
Example Request
cURL
curl -X POST https://your-domain.com/api/live-check \
-H "Content-Type: application/json" \
-d '{"emailData":"user@outlook.com|password|M.C509_BAY...|9e5f94bc-..."}'Success Response
200 OK
{
"email": "user@outlook.com",
"status": "SUCCESS",
"error": null,
"isLive": true
}2. Inbox Read
POST/api/inbox-read
Read messages from a Hotmail/Outlook inbox.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
emailData | string | โ Yes | โ | Account: email|password|refresh_token|client_id |
messageCount | int | โ No | 20 | Number of messages to fetch (5โ50) |
Example Request
cURL
curl -X POST https://your-domain.com/api/inbox-read \
-H "Content-Type: application/json" \
-d '{"emailData":"user@outlook.com|password|refresh_token|client_id","messageCount":20}'Success Response
200 OK
{
"email": "user@outlook.com",
"success": true,
"status": "SUCCESS",
"totalMessages": 3,
"error": null,
"messages": [
{
"subject": "Your verification code",
"from": "Facebook " ,
"preview": "73374 is your code...",
"date": "00:59 - 03/07/2026",
"hasAttachments": false,
"read": false
}
]
}3. Edu Mail Read
POST/api/edu-mail
Read messages from a Gmail Edu (EmailFake) account. No password required.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email | string | โ Yes | Edu email address (e.g. user@emailfake.com) |
Example Request
cURL
curl -X POST https://your-domain.com/api/edu-mail \
-H "Content-Type: application/json" \
-d '{"email":"user@emailfake.com"}'Success Response
200 OK
{
"email": "user@emailfake.com",
"error": null,
"mailSource": "emailfake",
"messages": [
{
"uid": "a1b2c3d4e5f67890",
"from": "Meta",
"subject": "Your Instagram code",
"date": "2026-05-23T10:30:00.000Z",
"code": "654321"
}
]
}4. TikTok Check
POST/api/tiktok-check
Check TikTok account status (Live / Die / Unknown).
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
line | string | โ Yes | Account info (see formats below) |
useProxy | bool | โ No | Use proxy (default: false) |
proxyKey | string | โ No | Proxy: ip:port:username:password |
line formats:tiktok_user ยท user123|password ยท user123|password|email@gmail.com|pwd|rt|cid
Example Request
cURL
curl -X POST https://your-domain.com/api/tiktok-check \
-H "Content-Type: application/json" \
-d '{"line":"tiktok_user|password123","useProxy":true,"proxyKey":"31.59.20.176:6754:user:pass"}'Response & Status Values
200 OK
{
"success": true,
"account": "tiktok_user|password123",
"status": "live",
"message": "LIVE"
}live
โ
Active
die
โ Expired
unknown
โ ๏ธ Undetermined
5. Get Inbox Message
POST/api/get-inbox
Read inbox messages via OAuth2, Graph API, or Roundcube.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
data | string | โ Yes | โ | Account info (see mode formats) |
mode | string | โ No | oauth | oauth ยท graph ยท roundcube |
Mode Formats
| Mode | Format |
|---|---|
oauth | email|refresh_token|client_id|client_secret |
graph | email|refresh_token|client_id|client_secret |
roundcube | user@wmhotmail.com|password |
Example Request
cURL
curl -X POST https://your-domain.com/api/get-inbox \
-H "Content-Type: application/json" \
-d '{"data":"user@outlook.com|refresh_token|client_id|client_secret","mode":"oauth"}'Success Response
200 OK
{
"email": "user@outlook.com",
"error": null,
"mailSource": "oauth",
"messages": [
{
"uid": "abc123def456",
"from": "Google " ,
"subject": "Your verification code",
"date": "2026-05-23 10:30:00",
"message": "97530 is your verification code",
"code": "97530"
}
]
}6. Renew Token
POST/api/renew-token
Refresh an OAuth2 token and get a new access token.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
emailData | string | โ Yes | Account: email|password|refresh_token|client_id |
Example Request
cURL
curl -X POST https://your-domain.com/api/renew-token \
-H "Content-Type: application/json" \
-d '{"emailData":"user@outlook.com|password|refresh_token|client_id"}'Success Response
200 OK
{
"email": "user@outlook.com",
"refreshToken": "M.C509_BAY...",
"clientId": "9e5f94bc-...",
"accessToken": "EwBoBMl6BAAU9Bat...",
"fullData": "user@outlook.com|password|M.C509_BAY...|9e5f94bc-...",
"success": true,
"status": "SUCCESS",
"error": null
}Error Handling
| HTTP Status | Meaning |
|---|---|
| 200 | โ
Success (check success/status field) |
| 400 | โ Bad request โ missing required field |
| 404 | โ Endpoint not found |
| 429 | โ ๏ธ Rate limit exceeded |
| 500 | ๐ฅ Internal server error |
Standard Error Format
{
"success": false,
"error": "Description of the error"
}Code Examples
PHP
PHP + cURL
$ch = curl_init('https://your-domain.com/api/live-check');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
'emailData' => 'user@outlook.com|password|refresh_token|client_id'
]));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response['isLive'] ? 'LIVE โ
' : 'DEAD โ';JavaScript
Fetch API
const response = await fetch('https://your-domain.com/api/inbox-read', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
emailData: 'user@outlook.com|password|refresh_token|client_id',
messageCount: 20
})
});
const data = await response.json();
if (data.status === 'SUCCESS') {
data.messages.forEach(msg => console.log(msg.subject));
}Python
Requests
import requests
response = requests.post('https://your-domain.com/api/tiktok-check', json={
'line': 'tiktok_user|password123',
'useProxy': True,
'proxyKey': '31.59.20.176:6754:user:pass'
})
data = response.json()
print(f"Status: {data['status'].upper()}")