Integrate disposable email

Quick start

1. POST /api/inbox → you get token + address.
2. Use the address to sign up or receive a verification code.
3. Poll GET /api/inbox/{token}/messages or use WebSocket (below).

Rate limits & headers

Creating inboxes (POST /api/inbox) is limited to 20 mailboxes per minute per IP. GET endpoints are not capped the same way — still avoid abusive polling.

When limited, you get 429 with:

• X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• Retry-After (seconds)

Endpoints

curl -X POST https://tkic.gg/api/inbox

{
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "address": "k7m2p9xq1a@tkic.gg",
  "created_at": 1710000000000
}

Example — website (fetch)

const base = "https://tkic.gg";

const { token, address } = await fetch(`${base}/api/inbox`, { method: "POST" }).then((r) =>
  r.json(),
);
console.log("Use this address:", address);

const poll = async () => {
  const { messages } = await fetch(`${base}/api/inbox/${token}/messages`).then((r) => r.json());
  if (messages.length) {
    const full = await fetch(`${base}/api/inbox/${token}/messages/${messages[0].id}`).then((r) =>
      r.json(),
    );
    console.log(full.message.subject, full.message.text_body);
  }
};
setInterval(poll, 5000);

Example — Discord bot (Node.js)

No CORS on the server side — use native fetch (Node 18+).

const BASE = "https://tkic.gg";

export async function createTempMail() {
  const res = await fetch(`${BASE}/api/inbox`, { method: "POST" });
  if (res.status === 429) {
    const body = await res.json();
    throw new Error(`Rate limit — retry in ${body.retry_after}s`);
  }
  return res.json();
}

export async function waitForCode(token, regex = /\b(\d{6})\b/) {
  for (let i = 0; i < 60; i++) {
    const { messages } = await fetch(`${BASE}/api/inbox/${token}/messages`).then((r) => r.json());
    if (messages[0]) {
      const { message } = await fetch(
        `${BASE}/api/inbox/${token}/messages/${messages[0].id}`,
      ).then((r) => r.json());
      const text = message.text_body ?? "";
      const m = text.match(regex);
      if (m) return m[1];
    }
    await new Promise((r) => setTimeout(r, 3000));
  }
  return null;
}

Real-time (WebSocket)

The web app uses wss://tkic.gg/ws?token={token}. When mail arrives, the server sends {"type":"new_message","message":{...}}. Useful to avoid aggressive polling.

Errors

Best practices

• Keep the token secret — it is the only key to the inbox.
• Respect the 20/min create limit; cache addresses if you need many.
• In production, handle 429 with backoff using Retry-After.
• Questions or abuse reports: tkic Discord.