tossinbox 0.1.3 → 0.1.5

package/README.md

@@ -55,7 +55,7 @@ $ tossinbox toss
 | Documented exit codes  | 0–4                     | none                | no                          |
 | MCP server for agents  | yes, built in           | no                  | no                          |
 | Runs headless / in CI  | yes                     | no                  | partial                     |
-| Upstream alive         | mail.tm + mail.gw + GuerrillaMail | varies              | many wrap the dead 1secmail |
+| Upstream alive         | 7 providers, 4 stacks  | varies              | many wrap the dead 1secmail |
 | Ads, trackers, popups  | none                    | the business model  | none                        |
 
 Checked September 2026. If a cell is wrong, open an issue and win the argument.
@@ -107,7 +107,7 @@ tossinbox wait --code --json
 
 | Command | Description |
 |---|---|
-| `spawn` | Create a new disposable inbox (`-p provider`, `-l label`) |
+| `spawn` | Create a new disposable inbox (`-p provider`, `-l label`). If the provider is down, another one is used automatically — `--no-failover` opts out |
 | `list` | List messages (`-a address`) |
 | `read <id>` | Read a full message, including any detected code |
 | `wait` | Poll until a message arrives (`-f sender`, `-s subject`, `-c` extract code, `-t timeout` max 600s) |
@@ -218,6 +218,10 @@ machine-readable and kept up to date.
 | `mailtm` (default) | not required | mail.tm — reliable, fast |
 | `mailgw` | not required | mail.gw — mail.tm-compatible API on independent infrastructure |
 | `guerrillamail` | not required | GuerrillaMail — classic fallback |
+| `tempmaillol` | not required | tempmail.lol — random inbox on rotating domains |
+| `tempmailio` | not required | temp-mail.io — server-generated address, `toss` deletes server-side |
+| `tempmailplus` | not required | tempmail.plus — pick-your-name inbox on 9 public domains |
+| `maildrop` | not required | maildrop.cc — public inbox on one stable domain |
 
 Adding a provider means implementing a small interface (`createInbox`,
 `listMessages`, `readMessage`, optional `destroyInbox`) — PRs welcome.
@@ -225,7 +229,7 @@ Adding a provider means implementing a small interface (`createInbox`,
 ## FAQ
 
 **Is it really free?**
-Yes. MIT-licensed, and all three upstream providers are free with no API keys.
+Yes. MIT-licensed, and all seven upstream providers are free with no API keys.
 
 **Can it send email?**
 No — receive-only by design. TossInbox exists for privacy and testing and
@@ -235,6 +239,12 @@ ships no bulk-send or bulk-signup mode.
 Yes, anywhere Node.js 18+ runs. `npx tossinbox@latest spawn`
 works in PowerShell exactly the same.
 
+**What if a provider is down?**
+`spawn` fails over automatically: it retries the create against the remaining
+providers and reports the switch (human mode prints a `⚠` warning and
+`provider : mailtm (failover from mailgw)`; `--json` returns a `failover`
+object). Use `--no-failover` if you need the chosen provider or nothing.
+
 **A site blocked my disposable address. What now?**
 Some sites blocklist known disposable domains. Try the other provider:
 `tossinbox spawn -p guerrillamail`. If both are blocked, the site wins that
@@ -256,9 +266,9 @@ round.
 - [x] Homebrew tap: `brew install mohamed-khairy-5i/tap/tossinbox`
 - [x] Project website at [tossinbox.pages.dev](https://tossinbox.pages.dev/)
 - [x] Publish `tossinbox` + `tossinbox-mcp` to the [npm registry](https://www.npmjs.com/package/tossinbox)
-- [ ] `mail.gw` provider (mail.tm-compatible API — small lift)
-- [ ] `tempmail.lol` provider (free API)
-- [ ] Provider failover: auto-switch when a provider is down
+- [x] `mail.gw` provider (v0.1.3)
+- [x] Four more providers: `tempmail.lol`, `temp-mail.io`, `tempmail.plus`, `maildrop.cc` (v0.1.4)
+- [x] Provider failover: auto-switch when a provider is down (v0.1.5)
 - [ ] Homebrew core formula (after community adoption)
 
 ## Documentation

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
-import { DEFAULT_PROVIDER, getProvider, listProviders, listSavedInboxes, removeInbox, clearInboxes, resolveInbox, saveInbox, statePath, waitForMessage, sleep, htmlToText, ProviderError, } from "./core/index.js";
+import { DEFAULT_PROVIDER, createInboxWithFailover, getProvider, listProviders, listSavedInboxes, removeInbox, clearInboxes, resolveInbox, saveInbox, statePath, waitForMessage, sleep, htmlToText, ProviderError, } from "./core/index.js";
 import { VERSION } from "./version.js";
 /* Documented exit codes:
  * 0  success
@@ -78,20 +78,32 @@ function printMessageHuman(message, withBody) {
 /* ------------------------------------------------------------------ */
 program
     .command("spawn")
-    .description("Create a new disposable inbox")
+    .description("Create a new disposable inbox (automatically falls back to another provider when the chosen one is down)")
     .option("-p, --provider <name>", "email provider (see: providers)", DEFAULT_PROVIDER)
     .option("-l, --label <label>", "optional label to identify this inbox")
+    .option("--no-failover", "fail if the chosen provider is down instead of falling back to another one")
     .action(async (opts) => {
     try {
-        const provider = providerOrExit(opts.provider);
-        const inbox = await provider.createInbox({ label: opts.label });
+        providerOrExit(opts.provider); // unknown name = usage error before any network call
+        const { inbox, switched, warnings } = await createInboxWithFailover({
+            requested: opts.provider,
+            label: opts.label,
+            failover: opts.failover,
+        });
         await saveInbox(inbox);
         if (jsonMode()) {
-            out({ ok: true, inbox });
+            out({
+                ok: true,
+                inbox,
+                ...(switched ? { failover: { requested: opts.provider, used: inbox.provider } } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
+            });
             return;
         }
+        for (const warning of warnings)
+            console.error(`⚠ ${warning}`);
         console.log(`✔ Inbox ready : ${inbox.address}`);
-        console.log(`  provider    : ${inbox.provider}`);
+        console.log(`  provider    : ${inbox.provider}${switched ? ` (failover from ${opts.provider})` : ""}`);
         if (inbox.label)
             console.log(`  label       : ${inbox.label}`);
         console.log(`  state file  : ${statePath()}`);

package/dist/core/failover.js

@@ -0,0 +1,66 @@
+import { providers } from "./index.js";
+import { ProviderError } from "./types.js";
+/** A failure that automatic failover is allowed to recover from: network-level
+ *  errors (no status) and server-side trouble (5xx) or throttling (429).
+ *  A plain 4xx is a real request problem — switching providers cannot fix it. */
+function isTransient(err) {
+    if (!(err instanceof ProviderError))
+        return true; // network-level → transient
+    const { status } = err;
+    return status === undefined || status === 429 || status >= 500;
+}
+function describe(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Create an inbox, falling back to other providers when the requested one is
+ * down. The requested provider is always tried first; the remaining providers
+ * follow registration order (best default first). Every failed attempt is
+ * recorded as a warning so humans and agents can see exactly what happened.
+ */
+export async function createInboxWithFailover(options = {}) {
+    const failover = options.failover !== false;
+    const requestedName = options.requested ?? Object.keys(providers)[0];
+    const requested = providers[requestedName];
+    if (!requested) {
+        const known = Object.keys(providers).join(", ");
+        throw new Error(`Unknown provider "${requestedName}". Available providers: ${known}`);
+    }
+    // Registration order, requested provider first.
+    const candidates = [
+        requested,
+        ...Object.values(providers).filter((p) => p.name !== requested.name),
+    ];
+    const warnings = [];
+    let firstError;
+    for (let i = 0; i < candidates.length; i++) {
+        const candidate = candidates[i];
+        try {
+            const inbox = await candidate.createInbox({ label: options.label });
+            return {
+                inbox,
+                switched: i > 0,
+                warnings,
+            };
+        }
+        catch (err) {
+            firstError ??= err;
+            warnings.push(`${candidate.name}: ${describe(err)}`);
+            // A non-transient 4xx on the REQUESTED provider is a real request
+            // problem (bad payload, blocked domain…) — retrying others would just
+            // mask it. Only when the user did not explicitly pick a provider do we
+            // fall through anyway, because they never asked for this one by name.
+            if (!isTransient(err) && options.requested)
+                throw err;
+            if (!failover)
+                throw err;
+        }
+    }
+    // Every candidate failed. Re-throw the requested provider's original error
+    // (it names the provider the user actually asked for) with a failover note.
+    const base = describe(firstError);
+    const others = candidates.length - 1;
+    throw new ProviderError(requestedName, others > 0
+        ? `${base} — failover also tried ${others} other provider(s) without success`
+        : base);
+}

package/dist/core/index.js

@@ -1,13 +1,22 @@
 import { mailTm, mailGw } from "./providers/mailtm.js";
 import { guerrillaMail } from "./providers/guerrillamail.js";
+import { tempmailLol } from "./providers/tempmaillol.js";
+import { tempmailIo } from "./providers/tempmailio.js";
+import { tempmailPlus } from "./providers/tempmailplus.js";
+import { maildrop } from "./providers/maildrop.js";
 export * from "./types.js";
 export { extractCode, htmlToText } from "./otp.js";
 export * from "./state.js";
 export { waitForMessage, sleep } from "./wait.js";
+export { createInboxWithFailover } from "./failover.js";
 export const providers = {
     [mailTm.name]: mailTm,
     [mailGw.name]: mailGw,
     [guerrillaMail.name]: guerrillaMail,
+    [tempmailLol.name]: tempmailLol,
+    [tempmailIo.name]: tempmailIo,
+    [tempmailPlus.name]: tempmailPlus,
+    [maildrop.name]: maildrop,
 };
 export const DEFAULT_PROVIDER = mailTm.name;
 export function getProvider(name) {

package/dist/core/providers/maildrop.js

@@ -0,0 +1,87 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://api.maildrop.cc/graphql/graphql";
+const HOST = "api.maildrop.cc";
+const REQUEST_TIMEOUT_MS = 20_000;
+function randomMailbox(length = 10) {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const bytes = randomBytes(length);
+    let out = "";
+    for (let i = 0; i < length; i++)
+        out += alphabet[bytes[i] % alphabet.length];
+    return out;
+}
+async function gql(query, variables) {
+    const res = await fetch(BASE, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "User-Agent": `tossinbox/${VERSION}`,
+        },
+        body: JSON.stringify({ query, variables }),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch((err) => {
+        throw networkError(err, "maildrop", HOST, REQUEST_TIMEOUT_MS);
+    });
+    if (res.status >= 500) {
+        throw new ProviderError("maildrop", `HTTP ${res.status} from ${HOST} — provider is down or having trouble; retry, or switch with --provider`, res.status);
+    }
+    const body = (await res.json().catch(() => undefined));
+    if (!body)
+        throw new ProviderError("maildrop", `HTTP ${res.status} — unexpected response`, res.status);
+    const firstError = body.errors?.[0]?.message;
+    if (firstError)
+        throw new ProviderError("maildrop", firstError, res.ok ? undefined : res.status);
+    if (!res.ok || !body.data) {
+        throw new ProviderError("maildrop", `HTTP ${res.status} — unexpected response`, res.status);
+    }
+    return body.data;
+}
+const INBOX_QUERY = `query ($mailbox: String!) { inbox(mailbox: $mailbox) { id headerfrom subject date } }`;
+const MESSAGE_QUERY = `query ($mailbox: String!, $id: String!) { message(mailbox: $mailbox, id: $id) { id headerfrom subject date html } }`;
+/** maildrop.cc inboxes are deterministic: every mailbox @maildrop.cc exists.
+ *  Spawn mints a fresh random mailbox name; no account or auth is involved. */
+export const maildrop = {
+    name: "maildrop",
+    description: "maildrop.cc — public inbox on one stable domain, no API key required",
+    async createInbox(options) {
+        const inbox = {
+            provider: this.name,
+            address: `${randomMailbox()}@maildrop.cc`,
+            label: options?.label,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        const mailbox = inbox.address.split("@")[0] ?? "";
+        const data = await gql(INBOX_QUERY, { mailbox });
+        return (data.inbox ?? []).map((m) => ({
+            id: m.id,
+            from: m.headerfrom ?? "unknown",
+            subject: m.subject ?? "(no subject)",
+            createdAt: m.date,
+        }));
+    },
+    async readMessage(inbox, id) {
+        const mailbox = inbox.address.split("@")[0] ?? "";
+        const data = await gql(MESSAGE_QUERY, { mailbox, id });
+        const m = data.message;
+        if (!m) {
+            throw new ProviderError("maildrop", "Message not found — re-list messages to see what is currently in the inbox");
+        }
+        const message = {
+            id,
+            from: m.headerfrom ?? "unknown",
+            subject: m.subject ?? "(no subject)",
+            createdAt: m.date,
+            html: m.html,
+        };
+        message.code = extractCode(message.html);
+        return message;
+    },
+};

package/dist/core/providers/tempmailio.js

@@ -0,0 +1,116 @@
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://api.internal.temp-mail.io";
+const HOST = "api.internal.temp-mail.io";
+const REQUEST_TIMEOUT_MS = 20_000;
+async function call(method, path, body) {
+    const res = await fetch(`${BASE}${path}`, {
+        method,
+        headers: {
+            Accept: "application/json",
+            "User-Agent": `tossinbox/${VERSION}`,
+            ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch((err) => {
+        throw networkError(err, "tempmailio", HOST, REQUEST_TIMEOUT_MS);
+    });
+    if (res.status >= 500) {
+        throw new ProviderError("tempmailio", `HTTP ${res.status} from ${HOST} — provider is down or having trouble; retry, or switch with --provider`, res.status);
+    }
+    return res;
+}
+async function callJson(method, path, body) {
+    const res = await call(method, path, body);
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const data = (await res.json());
+            if (typeof data.message === "string")
+                detail = `: ${data.message}`;
+        }
+        catch {
+            // ignore body parse errors
+        }
+        throw new ProviderError("tempmailio", `HTTP ${res.status}${detail}`, res.status);
+    }
+    return (await res.json());
+}
+/** The messages endpoint returns full bodies, so readMessage re-lists and picks.
+ *  A brand-new address can transiently 400 with "Email not found" right after
+ *  creation (eventual consistency upstream) — retry once before giving up. */
+async function fetchMessages(address) {
+    try {
+        return await callJson("GET", `/api/v3/email/${encodeURIComponent(address)}/messages`);
+    }
+    catch (err) {
+        if (err instanceof ProviderError && err.status === 400) {
+            await new Promise((r) => setTimeout(r, 1200));
+            return callJson("GET", `/api/v3/email/${encodeURIComponent(address)}/messages`);
+        }
+        throw err;
+    }
+}
+export const tempmailIo = {
+    name: "tempmailio",
+    description: "temp-mail.io — disposable email with 10+ rotating domains, no API key required",
+    async createInbox(options) {
+        const data = await callJson("POST", "/api/v3/email/new", { min_name_length: 10, max_name_length: 10 });
+        if (!data.email || !data.token) {
+            throw new ProviderError("tempmailio", "Unexpected response while creating inbox");
+        }
+        const inbox = {
+            provider: this.name,
+            address: data.email,
+            label: options?.label,
+            token: data.token,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        const list = await fetchMessages(inbox.address);
+        return list.map((m, i) => ({
+            id: String(m.mail_id ?? m.id ?? i),
+            from: m.from ?? "unknown",
+            fromName: m.from_name,
+            subject: m.subject ?? "(no subject)",
+            intro: m.body_text ? m.body_text.slice(0, 120) : undefined,
+            createdAt: m.created_at,
+        }));
+    },
+    async readMessage(inbox, id) {
+        const list = await fetchMessages(inbox.address);
+        const email = list.find((m, i) => String(m.mail_id ?? m.id ?? i) === id);
+        if (!email) {
+            throw new ProviderError("tempmailio", "Message not found — re-list messages to see what is currently in the inbox");
+        }
+        const message = {
+            id,
+            from: email.from ?? "unknown",
+            fromName: email.from_name,
+            subject: email.subject ?? "(no subject)",
+            intro: email.body_text ? email.body_text.slice(0, 120) : undefined,
+            createdAt: email.created_at,
+            text: email.body_text,
+            html: email.body_html,
+        };
+        message.code = extractCode(message.text) ?? extractCode(message.html);
+        return message;
+    },
+    async destroyInbox(inbox) {
+        if (!inbox.token)
+            return;
+        try {
+            await call("DELETE", `/api/v3/email/${encodeURIComponent(inbox.address)}`, {
+                token: inbox.token,
+            });
+        }
+        catch {
+            // best effort: local removal always happens regardless
+        }
+    },
+};

package/dist/core/providers/tempmaillol.js

@@ -0,0 +1,99 @@
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://api.tempmail.lol";
+const HOST = "api.tempmail.lol";
+const REQUEST_TIMEOUT_MS = 20_000;
+async function call(method, path, body) {
+    const res = await fetch(`${BASE}${path}`, {
+        method,
+        headers: {
+            Accept: "application/json",
+            "User-Agent": `tossinbox/${VERSION}`,
+            ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch((err) => {
+        throw networkError(err, "tempmaillol", HOST, REQUEST_TIMEOUT_MS);
+    });
+    if (res.status >= 500) {
+        throw new ProviderError("tempmaillol", `HTTP ${res.status} from ${HOST} — provider is down or having trouble; retry, or switch with --provider`, res.status);
+    }
+    return res;
+}
+async function callJson(method, path, body) {
+    const res = await call(method, path, body);
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const data = (await res.json());
+            if (typeof data.message === "string")
+                detail = `: ${data.message}`;
+        }
+        catch {
+            // ignore body parse errors
+        }
+        throw new ProviderError("tempmaillol", `HTTP ${res.status}${detail}`, res.status);
+    }
+    return (await res.json());
+}
+/** tempmail.lol list responses may omit per-email ids; synthesize a stable one */
+function synthesizedId(email, index) {
+    return email.id ?? `${email.date ?? "undated"}#${index}`;
+}
+export const tempmailLol = {
+    name: "tempmaillol",
+    description: "tempmail.lol — random inbox with rotating domains, no API key required",
+    async createInbox(options) {
+        const data = await callJson("POST", "/v2/inbox/create");
+        if (!data.address || !data.token) {
+            throw new ProviderError("tempmaillol", "Unexpected response while creating inbox");
+        }
+        const inbox = {
+            provider: this.name,
+            address: data.address,
+            label: options?.label,
+            token: data.token,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        if (!inbox.token)
+            throw new ProviderError("tempmaillol", "Inbox is missing its API token");
+        const data = await callJson("GET", `/v2/inbox?token=${encodeURIComponent(inbox.token)}`);
+        if (data.expired) {
+            throw new ProviderError("tempmaillol", "Inbox has expired on tempmail.lol — spawn a new one");
+        }
+        return (data.emails ?? []).map((e, i) => ({
+            id: synthesizedId(e, i),
+            from: e.from ?? "unknown",
+            subject: e.subject ?? "(no subject)",
+            createdAt: e.date,
+        }));
+    },
+    async readMessage(inbox, id) {
+        if (!inbox.token)
+            throw new ProviderError("tempmaillol", "Inbox is missing its API token");
+        const data = await callJson("GET", `/v2/inbox?token=${encodeURIComponent(inbox.token)}`);
+        if (data.expired) {
+            throw new ProviderError("tempmaillol", "Inbox has expired on tempmail.lol — spawn a new one");
+        }
+        const email = (data.emails ?? []).find((e, i) => synthesizedId(e, i) === id);
+        if (!email) {
+            throw new ProviderError("tempmaillol", "Message not found — it may have been dropped when the inbox rolled over; re-list messages");
+        }
+        const message = {
+            id,
+            from: email.from ?? "unknown",
+            subject: email.subject ?? "(no subject)",
+            createdAt: email.date,
+            text: email.body,
+            html: email.html,
+        };
+        message.code = extractCode(message.text) ?? extractCode(message.html);
+        return message;
+    },
+};

package/dist/core/providers/tempmailplus.js

@@ -0,0 +1,119 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { extractCode } from "../otp.js";
+import { networkError } from "../net.js";
+import { VERSION } from "../../version.js";
+const BASE = "https://tempmail.plus";
+const HOST = "tempmail.plus";
+const REQUEST_TIMEOUT_MS = 20_000;
+/** Public domains advertised by the tempmail.plus web client. The first one
+ *  is the service default and is the one TossInbox spawns on. */
+const DOMAIN = "mailto.plus";
+function randomUser(length = 12) {
+    const alphabet = "abcdefghijklmnopqrstuvwxyz0123456789";
+    const bytes = randomBytes(length);
+    let out = "";
+    for (let i = 0; i < length; i++)
+        out += alphabet[bytes[i] % alphabet.length];
+    return out;
+}
+function timeToIso(ts) {
+    if (!ts)
+        return undefined;
+    // Guard against seconds vs milliseconds epochs
+    return new Date(ts < 1e12 ? ts * 1000 : ts).toISOString();
+}
+async function call(method, path, body) {
+    const res = await fetch(`${BASE}${path}`, {
+        method,
+        headers: {
+            Accept: "application/json",
+            "User-Agent": `tossinbox/${VERSION}`,
+            ...(body ? { "Content-Type": "application/json" } : {}),
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    }).catch((err) => {
+        throw networkError(err, "tempmailplus", HOST, REQUEST_TIMEOUT_MS);
+    });
+    if (res.status >= 500) {
+        throw new ProviderError("tempmailplus", `HTTP ${res.status} from ${HOST} — provider is down or having trouble; retry, or switch with --provider`, res.status);
+    }
+    return res;
+}
+async function callJson(method, path, body) {
+    const res = await call(method, path, body);
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const data = (await res.json());
+            if (typeof data.message === "string")
+                detail = `: ${data.message}`;
+        }
+        catch {
+            // ignore body parse errors
+        }
+        throw new ProviderError("tempmailplus", `HTTP ${res.status}${detail}`, res.status);
+    }
+    return (await res.json());
+}
+/** tempmail.plus inboxes are deterministic: any address on a public domain
+ *  exists and can be read by anyone who knows it. Spawn mints a fresh random
+ *  local part; messages are then fetched by address. */
+export const tempmailPlus = {
+    name: "tempmailplus",
+    description: "tempmail.plus — pick-your-name inbox on 9 public domains, no API key required",
+    async createInbox(options) {
+        const inbox = {
+            provider: this.name,
+            address: `${randomUser()}@${DOMAIN}`,
+            label: options?.label,
+            createdAt: new Date().toISOString(),
+        };
+        return inbox;
+    },
+    async listMessages(inbox) {
+        const data = await callJson("GET", `/api/mails/?email=${encodeURIComponent(inbox.address)}&first_id=0`);
+        return (data.mail_list ?? []).map((m) => ({
+            id: String(m.id),
+            from: m.from ?? "unknown",
+            fromName: m.from_name,
+            subject: m.subject ?? "(no subject)",
+            createdAt: timeToIso(m.time),
+        }));
+    },
+    async readMessage(inbox, id) {
+        const data = await callJson("GET", `/api/mails/${encodeURIComponent(id)}?email=${encodeURIComponent(inbox.address)}&first_id=-1`);
+        if (!data.result) {
+            throw new ProviderError("tempmailplus", "Message not found — re-list messages to see what is currently in the inbox");
+        }
+        const message = {
+            id,
+            from: data.from ?? "unknown",
+            fromName: data.from_name,
+            subject: data.subject ?? "(no subject)",
+            createdAt: timeToIso(data.time),
+            text: data.text,
+            html: data.html,
+        };
+        message.code = extractCode(message.text) ?? extractCode(message.html);
+        return message;
+    },
+    async destroyInbox(inbox) {
+        try {
+            const data = await callJson("GET", `/api/mails/?email=${encodeURIComponent(inbox.address)}&first_id=0`);
+            const list = data.mail_list ?? [];
+            if (list.length === 0)
+                return;
+            await call("DELETE", "/api/mails", {
+                email: inbox.address,
+                first_id: data.first_id ?? 0,
+                last_id: data.last_id ?? 0,
+                force: true,
+            });
+        }
+        catch {
+            // best effort: local removal always happens regardless
+        }
+    },
+};

package/dist/mcp.js

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { DEFAULT_PROVIDER, getProvider, resolveInbox, saveInbox, waitForMessage, htmlToText, } from "./core/index.js";
+import { DEFAULT_PROVIDER, createInboxWithFailover, getProvider, resolveInbox, saveInbox, waitForMessage, htmlToText, } from "./core/index.js";
 import { VERSION } from "./version.js";
 function text(result, isError = false) {
     return {
@@ -40,17 +40,24 @@ export async function startMcpServer() {
         title: "Create a disposable inbox",
         description: "Create a brand new disposable email inbox. The inbox is saved locally so the other tools can use it. Returns the full email address to use in sign-up forms.",
         inputSchema: {
-            provider: z.string().optional().describe(`Provider name (default: "${DEFAULT_PROVIDER}", see the providers list)`),
+            provider: z.string().optional().describe(`Provider name (default: "${DEFAULT_PROVIDER}", see the providers list). If the provider is down, another one is used automatically unless no_failover is set`),
             label: z.string().optional().describe("Optional label to identify this inbox"),
+            no_failover: z.boolean().optional().describe("Fail when the chosen provider is down instead of falling back to another one"),
         },
-    }, async ({ provider, label }) => {
+    }, async ({ provider, label, no_failover }) => {
         try {
-            const p = getProvider(provider);
-            const inbox = await p.createInbox({ label });
+            getProvider(provider); // unknown name = clean error before any network call
+            const { inbox, switched, warnings } = await createInboxWithFailover({
+                requested: provider,
+                label,
+                failover: !no_failover,
+            });
             await saveInbox(inbox);
             return text({
                 ok: true,
                 inbox: { address: inbox.address, provider: inbox.provider, label: inbox.label },
+                ...(switched ? { failover: { requested: provider ?? DEFAULT_PROVIDER, used: inbox.provider } } : {}),
+                ...(warnings.length > 0 ? { warnings } : {}),
                 hint: `Use address "${inbox.address}" in the sign-up form, then call wait_for_code after submitting it.`,
             });
         }

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Single source of truth for the runtime version string.
  *  Keep in sync with package.json — bump both on release. */
-export const VERSION = "0.1.3";
+export const VERSION = "0.1.5";

package/llms.txt

@@ -24,14 +24,16 @@ inboxes when done. It is designed agent-first: every CLI command supports
 
 ## CLI (binary: `tossinbox`)
 
-- `tossinbox spawn` — create a new disposable inbox (flags: `-p provider`, `-l label`)
+- `tossinbox spawn` — create a new disposable inbox (flags: `-p provider`, `-l label`);
+  if the provider is down, another one is used automatically (`--no-failover` opts out)
 - `tossinbox list` — list messages in an inbox (flag: `-a address`)
 - `tossinbox read <id>` — read a full message by id
 - `tossinbox wait --code` — poll until a message arrives and print its verification code
   (flags: `-f sender`, `-s subject`, `-t timeout`, `-i interval`)
+- `tossinbox watch` — stream new messages as they arrive until Ctrl-C (NDJSON with `--json`)
 - `tossinbox inboxes` — list locally saved inboxes
 - `tossinbox toss` — delete an inbox server-side and wipe local state (`--all` for all)
-- `tossinbox providers` — list providers (default: `mailtm`, also `guerrillamail`)
+- `tossinbox providers` — list providers (default: `mailtm`; also `mailgw`, `guerrillamail`, `tempmaillol`, `tempmailio`, `tempmailplus`, `maildrop`)
 
 All commands accept `--json`. Exit codes: 0 success, 1 error, 2 timeout,
 3 not found, 4 usage error (bad flags / unknown provider).
@@ -59,7 +61,9 @@ npx tossinbox@latest spawn
 
 ## Notes
 
-- Providers: `mailtm` (default) and `guerrillamail`; no API keys required.
+- Providers: `mailtm` (default), `mailgw`, `guerrillamail`, `tempmaillol`,
+  `tempmailio`, `tempmailplus`, `maildrop`; no API keys required. When a
+  provider is down, `spawn` fails over to another one automatically.
 - Local state is stored in `~/.tossinbox/state.json` (override with the
   `TOSSINBOX_STATE` environment variable) with 0600 permissions.
 - TossInbox intentionally has no bulk mode; use it for privacy and testing and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tossinbox",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.",
   "type": "module",
   "license": "MIT",