📡 API Documentation

{
  "success": true,
  "address": "silentfox482@unkn0wn.qzz.io",
  "keyId": "k_9f3a...b21c",
  "expiresIn": 3600,
  "usage": { "today": 1, "limit": 10 }
}

{ "error": "Custom handle requires Premium" }

{
  "success": true,
  "address": "silentfox482@unkn0wn.qzz.io",
  "count": 1,
  "emails": [
    {
      "id": "email_abc123",
      "from": "noreply@example.com",
      "subject": "Your verification code",
      "body": "Your code is 123456",
      "hasHtml": true,
      "timestamp": 1710000000000
    }
  ]
}

{ "error": "Address not found or expired" }

event: init
data: {"address":"silentfox482@unkn0wn.qzz.io","emails":[]}

: keep-alive

event: new_email
data: {"id":"email_abc123","from":"noreply@example.com","subject":"Hi","timestamp":1710000000000}

event: deleted
data: {"id":"email_abc123"}

event: bye
data: {"reason":"server_shutdown"}

const address = 'silentfox482@unkn0wn.qzz.io';
const key = 'pm_free_your_api_key_here';
const url = `https://mail.unknowns.app/api/v1/emails/stream`
  + `?address=${encodeURIComponent(address)}&key=${key}`;

const es = new EventSource(url); // auto-reconnects

es.addEventListener('init', e => {
  const snap = JSON.parse(e.data);
  console.log('Snapshot:', snap.emails.length, 'emails');
});
es.addEventListener('new_email', e => {
  const mail = JSON.parse(e.data);
  console.log('New:', mail.from, '—', mail.subject);
});
es.addEventListener('deleted', e => console.log('Deleted', JSON.parse(e.data).id));
es.addEventListener('bye', () => es.close());
es.addEventListener('error', e => console.warn('Stream error', e));

import json, requests, sseclient  # pip install sseclient-py

ADDRESS = "silentfox482@unkn0wn.qzz.io"
KEY = "pm_free_your_api_key_here"
URL = "https://mail.unknowns.app/api/v1/emails/stream"

resp = requests.get(
    URL,
    params={"address": ADDRESS},
    headers={"X-API-Key": KEY, "Accept": "text/event-stream"},
    stream=True,
)
client = sseclient.SSEClient(resp)
for event in client.events():
    if event.event == "new_email":
        mail = json.loads(event.data)
        print(f"New: {mail['from']} — {mail['subject']}")
    elif event.event == "bye":
        break

curl -X POST https://mail.unknowns.app/api/v1/send \
  -H "X-API-Key: pm_pro_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "me@phant0m.qzz.io",
    "to": "friend@example.com",
    "subject": "Hello from Phantom Mail",
    "text": "Sent via the Phantom Mail API."
  }'

{ "success": true, "id": "msg_7f21ac" }

{ "error": "Sending requires a Premium API key" }

{
  "success": true,
  "plan": "premium",
  "usage": {
    "receive": { "today": 42, "limit": 500 },
    "send":    { "today": 3,  "limit": 50 }
  }
}

// keyPair was generated & saved when you first created the address:
// crypto.subtle.generateKey({ name: 'Ed25519' }, true, ['sign','verify'])
const address = 'silentfox482@unkn0wn.qzz.io';
const timestamp = Date.now();
const challenge = `phantom-claim:${address}:${timestamp}`;
const msg = new TextEncoder().encode(challenge);

const sigBuf = await crypto.subtle.sign(
  { name: 'Ed25519' }, keyPair.privateKey, msg
);
const pubRaw = await crypto.subtle.exportKey('raw', keyPair.publicKey);

const b64 = buf => btoa(String.fromCharCode(...new Uint8Array(buf)));

const res = await fetch('https://mail.unknowns.app/api/v1/claim', {
  method: 'POST',
  headers: {
    'X-API-Key': 'pm_free_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    address,
    timestamp,
    publicKey: b64(pubRaw),
    signature: b64(sigBuf)
  })
});
console.log(await res.json()); // { success: true, address }

{ "success": true, "address": "silentfox482@unkn0wn.qzz.io" }

{ "error": "Invalid signature" }