tossinbox 0.1.4 → 0.1.6

package/README.md

@@ -7,6 +7,8 @@
 **Disposable email inboxes for humans and AI agents. Spawn a temporary inbox, wait for the OTP verification code, toss it.**
 
 [![CI](https://github.com/mohamed-khairy-5i/tossinbox/actions/workflows/ci.yml/badge.svg)](https://github.com/mohamed-khairy-5i/tossinbox/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/tossinbox?color=cb3837&label=npm)](https://www.npmjs.com/package/tossinbox)
+[![npm downloads](https://img.shields.io/npm/dm/tossinbox?color=cb3837&label=downloads)](https://www.npmjs.com/package/tossinbox?activeTab=versions)
 ![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)
 ![Node](https://img.shields.io/badge/node-18%2B-34d399.svg)
 ![MCP](https://img.shields.io/badge/MCP-server-222a39.svg)
@@ -55,7 +57,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         | 7 providers, 4 stacks  | varies              | many wrap the dead 1secmail |
+| Upstream alive         | 7 providers, 4 stacks, attachments on read | 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,9 +109,9 @@ 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 |
+| `read <id>` | Read a full message, including any detected code; lists attachments. `--html` prints the raw HTML body, `--save [dir]` downloads attachments + bodies to `<dir>/<message-id>/` |
 | `wait` | Poll until a message arrives (`-f sender`, `-s subject`, `-c` extract code, `-t timeout` max 600s) |
 | `watch` | Stream new messages until Ctrl-C — only new arrivals; `--json` = one JSON object per line (NDJSON) |
 | `inboxes` | List locally saved inboxes |
@@ -155,7 +157,7 @@ TossInbox ships with an MCP server exposing four tools:
 |---|---|
 | `create_inbox` | Create a disposable inbox and return its address |
 | `list_messages` | List messages in an inbox |
-| `read_message` | Read a full message, including any detected code |
+| `read_message` | Read a full message, including any detected code; reports attachment metadata and can save attachments + bodies to disk (`save_dir`) |
 | `wait_for_code` | Poll until a message arrives and return its verification code |
 
 ### Claude Desktop / Cursor / any MCP client
@@ -226,6 +228,12 @@ machine-readable and kept up to date.
 Adding a provider means implementing a small interface (`createInbox`,
 `listMessages`, `readMessage`, optional `destroyInbox`) — PRs welcome.
 
+**Attachments** (v0.1.6): full list + download on `mailtm`, `mailgw` and
+`tempmailplus`; `tempmailio` shows them when its upstream returns them
+(downloadable only if it exposes a URL); `tempmaillol`, `guerrillamail` and
+`maildrop` do not expose attachments upstream — TossInbox tells you that
+instead of guessing.
+
 ## FAQ
 
 **Is it really free?**
@@ -239,6 +247,18 @@ 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.
+
+**Can I download attachments?**
+Yes on `mailtm`, `mailgw` and `tempmailplus`; `tempmailio` shows them when its
+upstream exposes them; the other three providers have no attachments upstream.
+`tossinbox read <id> --save` writes them (plus the HTML/plain-text bodies) to
+`./tossinbox-attachments/<message-id>/`.
+
 **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
@@ -260,9 +280,10 @@ 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)
+- [x] Attachments & HTML bodies: `read --save` / `--html` (v0.1.6)
 - [ ] 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, saveMessageContent, statePath, waitForMessage, sleep, htmlToText, ProviderError, } from "./core/index.js";
 import { VERSION } from "./version.js";
 /* Documented exit codes:
  * 0  success
@@ -58,8 +58,26 @@ function jsonMessage(message, includeHtml = false) {
         code: message.code,
         text: message.text ?? (message.html ? htmlToText(message.html) : undefined),
         html: includeHtml ? message.html : undefined,
+        ...(message.attachments
+            ? {
+                attachments: message.attachments.map((a) => ({
+                    filename: a.filename,
+                    size: a.size,
+                    contentType: a.contentType,
+                })),
+            }
+            : {}),
     };
 }
+function formatSize(bytes) {
+    if (bytes === undefined)
+        return "?";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} kB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
 function printMessageHuman(message, withBody) {
     console.log(`✔ ${message.subject}`);
     console.log(`  from : ${message.fromName ? `${message.fromName} <${message.from}>` : message.from}`);
@@ -67,6 +85,12 @@ function printMessageHuman(message, withBody) {
         console.log(`  date : ${message.createdAt}`);
     if (message.code)
         console.log(`  code : ${message.code}`);
+    if (message.attachments && message.attachments.length > 0) {
+        console.log(`  attachments (${message.attachments.length}):`);
+        for (const a of message.attachments) {
+            console.log(`    - ${a.filename} (${formatSize(a.size)}${a.contentType ? `, ${a.contentType}` : ""})`);
+        }
+    }
     if (withBody) {
         const body = message.text ?? (message.html ? htmlToText(message.html) : "");
         if (body)
@@ -78,20 +102,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()}`);
@@ -132,8 +168,10 @@ program
 });
 program
     .command("read <id>")
-    .description("Read a full message by id")
+    .description("Read a full message by id (list attachments, optionally save them and the HTML body)")
     .option("-a, --address <address>", "inbox address (defaults to the most recent inbox)")
+    .option("--html", "print the raw HTML body instead of the plain-text version")
+    .option("--save [dir]", "save attachments + body.html/body.txt into <dir>/<message-id>/ (default dir: ./tossinbox-attachments)")
     .action(async (id, opts) => {
     try {
         const inbox = await resolveInbox(opts.address);
@@ -141,11 +179,38 @@ program
             fail(new Error("No saved inbox found. Run: tossinbox spawn"), EXIT_NOT_FOUND);
         const provider = providerOrExit(inbox.provider);
         const message = await provider.readMessage(inbox, id);
+        let saved;
+        if (opts.save !== undefined) {
+            const dir = typeof opts.save === "string" && opts.save.length > 0 ? opts.save : "./tossinbox-attachments";
+            try {
+                saved = await saveMessageContent(provider, inbox, message, dir);
+            }
+            catch (err) {
+                fail(err);
+            }
+        }
         if (jsonMode()) {
-            out({ ok: true, inbox: inbox.address, message: jsonMessage(message, true) });
+            out({
+                ok: true,
+                inbox: inbox.address,
+                message: jsonMessage(message, true),
+                ...(saved ? { saved } : {}),
+            });
             return;
         }
         printMessageHuman(message, true);
+        if (opts.html) {
+            if (message.html) {
+                console.log(`\n${message.html}\n`);
+            }
+            else {
+                console.error("⚠ this message has no HTML body — showing the plain-text version above");
+            }
+        }
+        if (saved) {
+            for (const f of saved)
+                console.log(`  ✔ saved ${f.filename} → ${f.path}`);
+        }
     }
     catch (err) {
         fail(err, err instanceof ProviderError && err.status === 404 ? EXIT_NOT_FOUND : EXIT_ERROR);
@@ -302,6 +367,9 @@ program
                             createdAt: summary.createdAt,
                             code: message?.code,
                             text: message?.text ?? (message?.html ? htmlToText(message.html) : undefined),
+                            ...(message?.attachments && message.attachments.length > 0
+                                ? { attachments: message.attachments.map((a) => ({ filename: a.filename, size: a.size })) }
+                                : {}),
                         };
                         console.log(JSON.stringify(event));
                     }

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

@@ -8,6 +8,8 @@ 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 { saveMessageContent, safeSegment } from "./save.js";
 export const providers = {
     [mailTm.name]: mailTm,
     [mailGw.name]: mailGw,

package/dist/core/providers/mailtm.js

@@ -133,6 +133,13 @@ function createMailTmLikeProvider(config) {
             const res = await request("GET", `${base}/messages/${encodeURIComponent(id)}`, { token: inbox.token });
             const m = await parseJson(res);
             const html = m.html && m.html.length > 0 ? m.html.join("\n") : undefined;
+            const attachments = (m.attachments ?? []).map((a) => ({
+                id: a.id,
+                filename: a.filename || "attachment.bin",
+                contentType: a.contentType,
+                size: a.size,
+                contentId: a.disposition === "inline" ? a.id : undefined,
+            }));
             const message = {
                 id: m.id,
                 from: m.from?.address ?? "unknown",
@@ -142,10 +149,24 @@ function createMailTmLikeProvider(config) {
                 createdAt: m.createdAt,
                 text: m.text,
                 html,
+                ...(attachments.length > 0 ? { attachments } : {}),
             };
             message.code = extractCode(message.text) ?? extractCode(message.html);
             return message;
         },
+        async downloadAttachment(inbox, messageId, attachment) {
+            if (!inbox.token)
+                throw new ProviderError(providerName, "Inbox is missing its API token");
+            if (!attachment.id) {
+                throw new ProviderError(providerName, `Attachment "${attachment.filename}" has no id to download`);
+            }
+            const url = `${base}/messages/${encodeURIComponent(messageId)}/attachment/${encodeURIComponent(attachment.id)}`;
+            const res = await request("GET", url, { token: inbox.token });
+            if (!res.ok) {
+                throw new ProviderError(providerName, `HTTP ${res.status} while downloading "${attachment.filename}"`, res.status);
+            }
+            return Buffer.from(await res.arrayBuffer());
+        },
         async destroyInbox(inbox) {
             if (!inbox.token || !inbox.accountId)
                 return;

package/dist/core/providers/tempmailio.js

@@ -54,6 +54,16 @@ async function fetchMessages(address) {
         throw err;
     }
 }
+/** The v3 API attachment objects vary between deployments; parse defensively. */
+function toAttachment(a) {
+    return {
+        id: a.id !== undefined ? String(a.id) : undefined,
+        filename: a.filename ?? a.name ?? "attachment.bin",
+        contentType: a.contentType ?? a.content_type ?? a.type,
+        size: a.size,
+        url: a.url,
+    };
+}
 export const tempmailIo = {
     name: "tempmailio",
     description: "temp-mail.io — disposable email with 10+ rotating domains, no API key required",
@@ -97,10 +107,28 @@ export const tempmailIo = {
             createdAt: email.created_at,
             text: email.body_text,
             html: email.body_html,
+            ...((email.attachments ?? []).length > 0
+                ? { attachments: (email.attachments ?? []).map(toAttachment) }
+                : {}),
         };
         message.code = extractCode(message.text) ?? extractCode(message.html);
         return message;
     },
+    async downloadAttachment(_inbox, _messageId, attachment) {
+        if (!attachment.url) {
+            throw new ProviderError("tempmailio", `temp-mail.io did not expose a download URL for "${attachment.filename}" — open the message in the provider UI to retrieve it`);
+        }
+        const res = await fetch(attachment.url, {
+            headers: { Accept: "*/*", "User-Agent": `tossinbox/${VERSION}` },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        }).catch((err) => {
+            throw networkError(err, "tempmailio", HOST, REQUEST_TIMEOUT_MS);
+        });
+        if (!res.ok) {
+            throw new ProviderError("tempmailio", `HTTP ${res.status} while downloading "${attachment.filename}"`, res.status);
+        }
+        return Buffer.from(await res.arrayBuffer());
+    },
     async destroyInbox(inbox) {
         if (!inbox.token)
             return;

package/dist/core/providers/tempmailplus.js

@@ -20,6 +20,11 @@ function randomUser(length = 12) {
 function timeToIso(ts) {
     if (!ts)
         return undefined;
+    if (typeof ts === "string") {
+        // Some endpoints return "YYYY-MM-DD HH:mm:ss" strings instead of epochs
+        const d = new Date(ts.includes("T") ? ts : ts.replace(" ", "T") + "Z");
+        return isNaN(d.getTime()) ? undefined : d.toISOString();
+    }
     // Guard against seconds vs milliseconds epochs
     return new Date(ts < 1e12 ? ts * 1000 : ts).toISOString();
 }
@@ -75,8 +80,8 @@ export const tempmailPlus = {
     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",
+            id: String(m.mail_id ?? m.id),
+            from: m.from_mail ?? m.from ?? "unknown",
             fromName: m.from_name,
             subject: m.subject ?? "(no subject)",
             createdAt: timeToIso(m.time),
@@ -87,18 +92,45 @@ export const tempmailPlus = {
         if (!data.result) {
             throw new ProviderError("tempmailplus", "Message not found — re-list messages to see what is currently in the inbox");
         }
+        const attachments = (data.attachments ?? []).map((a) => ({
+            id: a.attachment_id !== undefined ? String(a.attachment_id) : undefined,
+            filename: a.name || "attachment.bin",
+            size: a.size,
+            contentId: a.content_id || undefined,
+        }));
         const message = {
             id,
-            from: data.from ?? "unknown",
+            from: data.from_mail ?? data.from ?? "unknown",
             fromName: data.from_name,
             subject: data.subject ?? "(no subject)",
-            createdAt: timeToIso(data.time),
+            createdAt: timeToIso(data.time) ?? data.date,
             text: data.text,
             html: data.html,
+            ...(attachments.length > 0 ? { attachments } : {}),
         };
         message.code = extractCode(message.text) ?? extractCode(message.html);
         return message;
     },
+    async downloadAttachment(inbox, messageId, attachment) {
+        if (!attachment.id) {
+            throw new ProviderError("tempmailplus", `Attachment "${attachment.filename}" has no id to download`);
+        }
+        // Download endpoint as used by the tempmail.plus web client:
+        // /api/mails/{mailId}/attachments/{attachment_id}?email={address}&epin={pin?}
+        const url = `${BASE}/api/mails/${encodeURIComponent(messageId)}` +
+            `/attachments/${encodeURIComponent(attachment.id)}` +
+            `?email=${encodeURIComponent(inbox.address)}&epin=${encodeURIComponent(inbox.session ?? "")}`;
+        const res = await fetch(url, {
+            headers: { Accept: "*/*", "User-Agent": `tossinbox/${VERSION}` },
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        }).catch((err) => {
+            throw networkError(err, "tempmailplus", HOST, REQUEST_TIMEOUT_MS);
+        });
+        if (!res.ok) {
+            throw new ProviderError("tempmailplus", `HTTP ${res.status} while downloading "${attachment.filename}"`, res.status);
+        }
+        return Buffer.from(await res.arrayBuffer());
+    },
     async destroyInbox(inbox) {
         try {
             const data = await callJson("GET", `/api/mails/?email=${encodeURIComponent(inbox.address)}&first_id=0`);

package/dist/core/save.js

@@ -0,0 +1,41 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** Filesystem-safe single path segment: strips separators, traversal and
+ *  control characters, collapses blanks. */
+export function safeSegment(name, fallback) {
+    const cleaned = name
+        .replace(/[^A-Za-z0-9._ ()\[\]-]/g, "_")
+        .replace(/\.{2,}/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .trim();
+    return cleaned.length > 0 && cleaned !== "." && cleaned !== ".." ? cleaned.slice(0, 120) : fallback;
+}
+/** Save everything a message carries to disk: every attachment (when the
+ *  provider supports downloads) plus body.html / body.txt when present.
+ *  Files land in `<dir>/<message-id>/`. Shared by the CLI and the MCP server. */
+export async function saveMessageContent(provider, inbox, message, dir) {
+    const messageDir = path.join(path.resolve(dir), safeSegment(message.id, "message"));
+    fs.mkdirSync(messageDir, { recursive: true });
+    const saved = [];
+    for (const attachment of message.attachments ?? []) {
+        if (typeof provider.downloadAttachment !== "function") {
+            throw new Error(`provider "${provider.name}" does not support attachment downloads — try another provider`);
+        }
+        const bytes = await provider.downloadAttachment(inbox, message.id, attachment);
+        const filename = safeSegment(attachment.filename, "attachment.bin");
+        const target = path.join(messageDir, filename);
+        fs.writeFileSync(target, bytes);
+        saved.push({ kind: "attachment", filename, path: target, size: bytes.length });
+    }
+    if (message.html !== undefined) {
+        const target = path.join(messageDir, "body.html");
+        fs.writeFileSync(target, message.html, "utf8");
+        saved.push({ kind: "body.html", filename: "body.html", path: target, size: Buffer.byteLength(message.html) });
+    }
+    if (message.text !== undefined) {
+        const target = path.join(messageDir, "body.txt");
+        fs.writeFileSync(target, message.text, "utf8");
+        saved.push({ kind: "body.txt", filename: "body.txt", path: target, size: Buffer.byteLength(message.text) });
+    }
+    return saved;
+}

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, saveMessageContent, waitForMessage, htmlToText, } from "./core/index.js";
 import { VERSION } from "./version.js";
 function text(result, isError = false) {
     return {
@@ -23,6 +23,15 @@ function messageJson(message, includeHtml = false) {
         code: message.code,
         text: message.text ?? (message.html ? htmlToText(message.html) : undefined),
         html: includeHtml ? message.html : undefined,
+        ...(message.attachments
+            ? {
+                attachments: message.attachments.map((a) => ({
+                    filename: a.filename,
+                    size: a.size,
+                    contentType: a.contentType,
+                })),
+            }
+            : {}),
     };
 }
 async function requireInbox(address) {
@@ -40,17 +49,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.`,
             });
         }
@@ -79,19 +95,28 @@ export async function startMcpServer() {
     });
     server.registerTool("read_message", {
         title: "Read a message",
-        description: "Read the full body of a message by id, including any verification code detected in it.",
+        description: "Read the full body of a message by id, including any verification code detected in it. Lists attachment metadata; pass save_dir to also save the attachments and the HTML body to disk (where the provider supports downloads).",
         inputSchema: {
             id: z.string().describe("Message id (from list_messages)"),
             address: z.string().optional().describe("Inbox address; defaults to the most recent inbox"),
+            save_dir: z.string().optional().describe('Directory to save attachments and body.html/body.txt into, written to <save_dir>/<message-id>/ (e.g. "/tmp")'),
         },
-    }, async ({ id, address }) => {
+    }, async ({ id, address, save_dir }) => {
         try {
             const inbox = await requireInbox(address);
             if (!inbox)
                 return text({ ok: false, error: "No saved inbox found. Call create_inbox first." }, true);
             const p = getProvider(inbox.provider);
             const message = await p.readMessage(inbox, id);
-            return text({ ok: true, message: messageJson(message, false) });
+            let saved;
+            if (save_dir) {
+                saved = await saveMessageContent(p, inbox, message, save_dir);
+            }
+            return text({
+                ok: true,
+                message: messageJson(message, false),
+                ...(saved ? { saved } : {}),
+            });
         }
         catch (err) {
             return text({ ok: false, error: err instanceof Error ? err.message : String(err) }, true);

package/dist/version.js

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

package/llms.txt

@@ -24,11 +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 read <id>` — read a full message by id; `--save [dir]` saves every attachment plus the
+  HTML/plain-text bodies to `<dir>/<message-id>/` (default dir `./tossinbox-attachments`),
+  `--html` prints the raw HTML body
 - `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`; events
+  include attachment names when a new message has them)
 - `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 `mailgw`, `guerrillamail`, `tempmaillol`, `tempmailio`, `tempmailplus`, `maildrop`)
@@ -42,7 +47,8 @@ Stdio MCP server exposing four tools:
 
 - `create_inbox` — create a disposable inbox, returns its email address
 - `list_messages` — list messages in an inbox
-- `read_message` — read a full message including any detected code
+- `read_message` — read a full message including any detected code; reports attachment metadata and
+  accepts an optional `save_dir` input that saves attachments + bodies to `<save_dir>/<message-id>/`
 - `wait_for_code` — poll until a message arrives and return its verification code
 
 Typical agent flow: `create_inbox` -> use the address in a signup form ->
@@ -59,7 +65,13 @@ 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.
+- Attachments: full list + download on `mailtm`, `mailgw` and `tempmailplus`;
+  `tempmailio` shows them when its upstream returns them (download only if it
+  exposes a URL); `tempmaillol`, `guerrillamail` and `maildrop` have no
+  attachment support upstream.
 - 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.4",
+  "version": "0.1.6",
   "description": "Disposable email inboxes for humans and AI agents. Spawn an inbox, wait for the OTP, toss it.",
   "type": "module",
   "license": "MIT",