API Documentation

Programmatic access to your Mighty Temp Mail account. Create inboxes, fetch messages, extract OTP codes — all from your scripts and apps.

Authentication

Every request must include your API key in the Authorization header:

Authorization: Bearer mk_live_YOUR_KEY_HERE

Generate a key from your dashboard. Keys look like mk_live_<32 hex chars>.

Your API key accesses the same account as your dashboard login. Inboxes, balance, and free-inbox counters are all shared.

Inboxes

Create an inbox

curl -X POST https://tempmail.heartsyncmatch.com/api/inboxes \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"localPart":"myinbox"}'

Body: localPart is optional. Omit it for a random address.

Response:

{
  "id": 42,
  "address": "myinbox@heartsyncmatch.com",
  "user_id": 1,
  "paid_with": "balance",
  "cost_cents": 250,
  "created_at": 1791292042
}

402 error if your balance is empty and free inboxes are used up:

{
  "error": "insufficient_balance",
  "required_cents": 250,
  "balance_cents": 0
}

List your inboxes

curl https://tempmail.heartsyncmatch.com/api/inboxes \
  -H "Authorization: Bearer YOUR_KEY"

Delete an inbox

curl -X DELETE https://tempmail.heartsyncmatch.com/api/inboxes/42 \
  -H "Authorization: Bearer YOUR_KEY"

Messages & OTP

Fetch messages (with optional long-polling)

Query parameters:

• ?wait=30 — hold the request open for up to 30 seconds, returning as soon as a new message arrives. Saves you from polling in a tight loop.
• ?since=1791292000 — only return messages received after this unix timestamp.

curl "https://tempmail.heartsyncmatch.com/api/inboxes/42/messages?wait=30" \
  -H "Authorization: Bearer YOUR_KEY"

Fetch a single message with automatic OTP extraction

Add ?otp=true and the response includes code (6-digit OTP) and magic_link (verification URL) extracted from the email content.

curl "https://tempmail.heartsyncmatch.com/api/messages/msg_1791292792644_ddebe13d?otp=true" \
  -H "Authorization: Bearer YOUR_KEY"

Response:

{
  "id": "msg_1791292792644_ddebe13d",
  "from": "noreply@example.com",
  "subject": "Your verification code",
  "body_text": "Your verification code is 344666",
  "code": "344666",
  "magic_link": null,
  "received_at": 1791292792
}

API keys

You can have up to 5 active keys at a time. Revoke old ones from the dashboard if you hit the limit.

Keys can be created with an optional expiration: Never, 30 days, 90 days, 6 months, or 1 year. Expired keys stop working automatically and no longer count toward your 5-key limit — but their metadata remains visible in the dashboard for reference.

Create a key with expiration

curl -X POST https://tempmail.heartsyncmatch.com/api/api-keys \
  -H "Authorization: Bearer YOUR_SESSION_OR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI pipeline","expires_in_days":90}'

Set expires_in_days to 0 or omit it for a key that never expires. Maximum is 730 days (2 years).

Examples

Python — create inbox, wait for OTP, extract code

import requests

API_KEY = "mk_live_YOUR_KEY"
BASE = "https://tempmail.heartsyncmatch.com"

# 1. Create an inbox
inbox = requests.post(
    f"{BASE}/api/inboxes",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"localPart": "python-test"},
).json()
print("Inbox:", inbox["address"])

# 2. Use inbox["address"] on the target service, then long-poll
messages = requests.get(
    f"{BASE}/api/inboxes/{inbox['id']}/messages?wait=30",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

# 3. Extract the OTP
msg = requests.get(
    f"{BASE}/api/messages/{messages[0]['id']}?otp=true",
    headers={"Authorization": f"Bearer {API_KEY}"},
).json()

print("OTP code:", msg["code"])

Node.js — same flow

const API_KEY = "mk_live_YOUR_KEY";
const BASE = "https://tempmail.heartsyncmatch.com";

const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// 1. Create an inbox
const inbox = await fetch(`${BASE}/api/inboxes`, {
  method: "POST", headers, body: JSON.stringify({ localPart: "node-test" }),
}).then(r => r.json());

// 2. Long-poll for the message
const messages = await fetch(
  `${BASE}/api/inboxes/${inbox.id}/messages?wait=30`,
  { headers }
).then(r => r.json());

// 3. Extract the OTP
const msg = await fetch(
  `${BASE}/api/messages/${messages[0].id}?otp=true`,
  { headers }
).then(r => r.json());

console.log("OTP:", msg.code);

Rate limits

• Inbox creation: 30 per hour per account
• Long-poll wait: 30 seconds max per request
• Keys per account: 5

Need a higher limit or bulk operations? Contact us on WhatsApp.