Mail Fetch API Documentation
Direct REST interface to automatically query and fetch OTPs, 4-digit codes, verification links, household confirmations, and password reset links from your bot pool in under 15ms.
๐ Base URL
All requests must be made over secure HTTPS. Data is exchanged in standard JSON format.
๐ Authentication
Authenticate your requests using your secret API Key generated by your bot administrator. You can pass the key in three ways (in order of priority):
| Method | Header / Param | Example |
|---|---|---|
| Header (Recommended) | X-API-Key |
X-API-Key: hh_live_9a8b7c6d... |
| Bearer Token | Authorization |
Authorization: Bearer hh_live_9a8b... |
| Query / JSON Body | api_key |
{"api_key": "hh_live_9a8b..."} |
โฑ๏ธ Rate Limiting
To ensure high availability and prevent abuse, requests are throttled using a high-precision sliding-window rate limiter:
- Per-Key Limit:
60 requests / minute(customizable by Admin). - Per-IP Limit:
120 requests / minute.
When a rate limit is exceeded, the server responds with HTTP 429 Too Many Requests and includes a Retry-After header indicating how many seconds to wait.
๐ฅ Fetch Email Code / Link
Queries recent inbox items matching the recipient email address and category type. Returns raw HTML content, timestamp, and account country code.
Request Parameters
| Field | Type | Presence | Description |
|---|---|---|---|
mail / email |
string | REQUIRED | The target recipient email address (e.g. [email protected]). |
choice / type |
string | OPTIONAL | Email category to extract. Defaults to 4-digit. |
api_key |
string | REQUIRED | API key (if not passed in X-API-Key header). |
curl -X POST "https://opomail.store/api/v1/fetch" \
-H "X-API-Key: hh_live_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"mail": "[email protected]",
"choice": "4-digit"
}'
import requests
url = "https://opomail.store/api/v1/fetch"
headers = {
"X-API-Key": "hh_live_your_api_key_here",
"Content-Type": "application/json"
}
payload = {
"mail": "[email protected]",
"choice": "4-digit"
}
response = requests.post(url, headers=headers, json=payload, timeout=10)
data = response.json()
if data.get("status") == "success":
print("Country:", data.get("country_code"))
print("Timestamp:", data.get("timestamp"))
print("HTML Content:", data.get("html"))
else:
print("Error:", data.get("message"))
const response = await fetch("https://opomail.store/api/v1/fetch", {
method: "POST",
headers: {
"X-API-Key": "hh_live_your_api_key_here",
"Content-Type": "application/json"
},
body: JSON.stringify({
mail: "[email protected]",
choice: "4-digit"
})
});
const data = await response.json();
console.log(data);
<?php
$ch = curl_init("https://opomail.store/api/v1/fetch");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"X-API-Key: hh_live_your_api_key_here",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"mail" => "[email protected]",
"choice" => "4-digit"
]));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
payload, _ := json.Marshal(map[string]string{
"mail": "[email protected]",
"choice": "4-digit",
})
req, _ := http.NewRequest("POST", "https://opomail.store/api/v1/fetch", bytes.NewBuffer(payload))
req.Header.Set("X-API-Key", "hh_live_your_api_key_here")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Status:", resp.Status)
}
Success Response 200 OK
{
"status": "success",
"html": "<div class='email-wrapper'><p>Your sign-in code is <b>6206</b></p></div>",
"timestamp": "2026-08-26T04:35:00Z",
"country_code": "US",
"code": "6206",
"link": "https://netflix.com/verify",
"mail": "[email protected]",
"type": "sign_in"
}
No Matching Mail 200 OK
{
"status": "failed",
"error_code": "NO_MATCH",
"message": "No matching email found in recent mails.",
"mail": "[email protected]"
}
๐ Category Choices Reference
choice Parameter |
Description | Valid Lifetime Window |
|---|---|---|
4-digit / sign_in |
Netflix sign-in OTP, login codes, temporary device pin | 6 Hours |
household |
Netflix update household confirmation link / location pin | 48 Hours |
verification / verify |
15-minute / 10-minute security verification codes | 6 Hours |
reset / reset_link |
Password reset URL / security change links | 48 Hours |
2fa / two_factor |
Two-Factor authentication numeric security code | 6 Hours |
disney / chatgpt / hbomax |
Platform-specific codes and access confirmations | 6 Hours |
all |
Returns the single latest message matching any category | 48 Hours |
๐ฆ HTTP Status Codes & Error Codes
| HTTP Status | error_code |
Description & Resolution |
|---|---|---|
| 200 OK | - |
Request succeeded. Check status: success or status: failed. |
| 401 Unauthorized | MISSING_KEY |
No API key provided in headers or body. |
| 401 Unauthorized | INVALID_KEY |
The provided API key does not exist or has been deleted. |
| 403 Forbidden | FORBIDDEN_EMAIL |
Mail access denied. This API key is restricted and does not have permission for the requested email. |
| 403 Forbidden | KEY_EXPIRED |
The API key subscription duration has expired. Contact your administrator. |
| 403 Forbidden | KEY_DISABLED |
The API key has been paused by the administrator. |
| 400 Bad Request | INVALID_EMAIL |
Email format is missing or invalid. |
| 429 Rate Limited | RATE_LIMIT_EXCEEDED |
Exceeded 60 requests per minute. Wait for the Retry-After duration. |
๐งช Live API Playground
Test your API key and email queries live directly from your browser.
๐ฌ Developer Support & Custom Integrations
Need Direct Technical Assistance?
Have questions regarding API key generation, permissions setup, rate limit upgrades, or integrating custom Telegram/Discord bots with this API? Reach out directly via Telegram.