DEVELOPER REST API REFERENCE

Mailhavuzu REST API Reference & Integration Guide

Official REST interface to query live mailbox inventory, automate account purchasing, and stream verification codes in 1.5 seconds.

Authentication & Headers

Every API request requires your unique personal API key passed in the request header. You can generate or copy your key from the "API Access" section inside your dashboard.

// Required HTTP Request Header
X-Api-Key: mh_live_a1b2c3d4e5f6...

Base URL: https://mailhavuzu.com

GET /api/v1/stock

Returns available mailbox categories, real-time inventory count, and pricing.

curl -s -X GET "https://mailhavuzu.com/api/v1/stock" \
  -H "X-Api-Key: YOUR_API_KEY"
Sample Response (200 OK):
[
  {
    "id": 1,
    "category": "hotmail_fresh",
    "display_name": "Hotmail Taze Posta Kutusu",
    "display_domain": "@hotmail.com",
    "lifetime": "1-5 Saat",
    "price": 12.50,
    "stock": 420
  },
  {
    "id": 2,
    "category": "outlook_trusted",
    "display_name": "Outlook Dinlendirilmiş Kalıcı",
    "display_domain": "@outlook.com",
    "lifetime": "3-6 Ay",
    "price": 28.00,
    "stock": 85
  }
]
GET /api/v1/balance

Returns your active account balance.

curl -s -X GET "https://mailhavuzu.com/api/v1/balance" \
  -H "X-Api-Key: YOUR_API_KEY"
Sample Response (200 OK):
{
  "balance": 250.00
}
POST /api/v1/buy

Purchases mailboxes from the specified category using account balance and returns credentials immediately.

Field Type Description
id veya category Integer / String Product ID (e.g. 1) or Category slug (e.g. "hotmail_fresh")
quantity Integer Number of mailboxes to acquire (min: 1)
curl -s -X POST "https://mailhavuzu.com/api/v1/buy" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": 1, "quantity": 1}'
Sample Response (200 OK):
{
  "success": true,
  "mailboxes": [
    {
      "id": 8412,
      "email": "[email protected]",
      "password": "SamplePassword123!",
      "status": "active",
      "created_at": "2026-11-16 10:20:00"
    }
  ]
}
GET /api/v1/mail

Fetches incoming verification emails. Passing email or mailbox_id triggers an instant on-demand live fetch from Microsoft Graph API (1.5-second code retrieval).

Parameter Type Description
email String (Opsiyonel) Filters incoming mail for this specific address and triggers immediate live poll.
mailbox_id Integer (Opsiyonel) Mailbox ID returned by /api/v1/buy.
limit Integer (Opsiyonel) Max number of messages (default: 50, max: 200)
curl -s -X GET "https://mailhavuzu.com/api/v1/[email protected]" \
  -H "X-Api-Key: YOUR_API_KEY"
Sample Response (200 OK):
[
  {
    "id": 10523,
    "mailbox_id": 8412,
    "email": "[email protected]",
    "sender": "[email protected]",
    "subject": "184920 is your Instagram code",
    "extracted_code": "184920",
    "snippet": "To confirm your account, enter this code...",
    "received_at": "2026-11-16 10:21:15"
  }
]

Code Snippets (Python & Node.js)

Python (requests) - Purchase Inbox & Poll for OTP
import time
import requests

API_KEY = "YOUR_API_KEY"
HEADERS = {"X-Api-Key": API_KEY}
BASE_URL = "https://mailhavuzu.com/api/v1"

# 1. 1 Adet Posta Kutusu Satin Al
res = requests.post(f"{BASE_URL}/buy", json={"id": 1, "quantity": 1}, headers=HEADERS).json()
mailbox = res["mailboxes"][0]
email = mailbox["email"]
print(f"Posta Kutusu Teslim Alindi: {email}")

# 2. Onay Maili / Kodu Gelene Kadar Bekle (Canli polling)
print("Doğrulama kodu bekleniyor...")
for _ in range(20):
    time.sleep(3)
    mails = requests.get(f"{BASE_URL}/mail?email={email}", headers=HEADERS).json()
    if mails:
        latest = mails[0]
        code = latest.get("extracted_code")
        print(f"⚡ Kod Geldi: {code} (Gonderici: {latest['sender']})")
        break
Node.js / JavaScript (Fetch)
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://mailhavuzu.com/api/v1";

async function getStock() {
  const res = await fetch(`${BASE_URL}/stock`, {
    headers: { "X-Api-Key": API_KEY }
  });
  const data = await res.json();
  console.log("Mevcut Stoklar:", data);
}
getStock();

ZennoPoster & BAS Integration

Connecting Mailhavuzu to BAS or ZennoPoster is effortless using standard HTTP Request actions:

  1. Add Request Header: <code>X-Api-Key: mh_live_...</code>.
  2. Before filling registration forms, call <code>POST /api/v1/buy</code> to fetch a fresh inbox.
  3. Loop <code>GET /api/v1/mail?email={email}</code> until response array is non-empty, then extract <code>extracted_code</code> directly into the OTP input field.