{"id":"2d72958d-7827-450d-bfe5-c37d5518cc65","entityType":"agent","slug":"clawhub-psyb0t-docker-mailbox","name":"docker-mailbox","canonicalUrl":"https://www.xpersona.co/agent/clawhub-psyb0t-docker-mailbox","canonicalPath":"/agent/clawhub-psyb0t-docker-mailbox","generatedAt":"2026-10-11T00:31:38.498Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:17:22.290Z","emptyReason":null},"description":"Multi-mailbox IMAP/SMTP control plane exposed as a REST API + MCP server (streamable HTTP) on a single port. Read, search, send, mark-seen, and delete mail across multiple inboxes in one call — `GET /inbox` fans out across every IMAP account in parallel and returns a merged, newest-first feed. Use when you need an agent (or a script, or a curl one-liner) to drive one or more real mail accounts without standing up a webmail UI, a message store, or any per-provider client library. Stdlib `imaplib`/`smtplib` under the hood, FastAPI on top, bearer-token auth optional.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.2K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17fq93tmpky791n7516jcn08n83sfn2:docker-mailbox","sourceUrl":"https://clawhub.ai/psyb0t/docker-mailbox","homepage":"https://clawhub.ai/psyb0t/skills/docker-mailbox","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/psyb0t/docker-mailbox","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/psyb0t/skills/docker-mailbox","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"docker-mailbox technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:17:22.290Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:17:22.290Z","emptyReason":null},"stars":null,"forks":null,"downloads":1244,"packageName":null,"latestVersion":"1.2.3","tractionLabel":"1.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:17:22.217Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T22:17:22.290Z","lastCrawledAt":"2026-10-10T22:17:22.217Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T22:17:22.217Z","lastVerifiedAt":null,"highlights":[{"version":"1.2.3","createdAt":"2026-08-20T14:39:02.946Z","changelog":"- Updated setup and reference documentation in `references/setup.md`. - Removed redundant `skill-card.md` file. - No user-facing functionality changes; documentation cleanup only.","fileCount":4,"zipByteSize":12822},{"version":"1.2.2","createdAt":"2026-07-26T02:23:49.158Z","changelog":"docker-mailbox 1.2.2 - Updated SKILL.md language for improved clarity and conciseness, especially in security warnings and deletion guidance. - Expanded search example in `/inbox` documentation to include searching a specific folder. - Removed old skill-card.md file. - No functional or API changes; documentation only.","fileCount":4,"zipByteSize":12819},{"version":"1.2.1","createdAt":"2026-07-26T01:34:29.493Z","changelog":"- Added a \"Security & safety\" section to the documentation, detailing important warnings about destructive deletes, authentication/config best practices, and data handling. - Removed the file skill-card.md from the project. - No changes to functionality or API; changes are documentation and file organization only.","fileCount":4,"zipByteSize":12976},{"version":"1.2.0","createdAt":"2026-05-18T04:23:22.707Z","changelog":"No visible file changes detected for version 1.2.0. No changes to functionality or documentation.","fileCount":4,"zipByteSize":11964},{"version":"1.1.0","createdAt":"2026-05-18T03:31:38.641Z","changelog":"No file changes detected for this release. - No user-facing changes or updates in this version. - Functionality and documentation remain the same as the previous release.","fileCount":3,"zipByteSize":9882},{"version":"1.0.0","createdAt":"2026-05-18T03:17:43.482Z","changelog":"docker-mailbox v1.0.0 - Initial release providing a unified REST API and MCP server for controlling multiple IMAP/SMTP mailboxes on a single port. - Supports reading, searching, sending, marking as seen, and deleting mail across multiple inboxes in one call. - Unified `GET /inbox` endpoint fans out searches across all configured mailboxes and merges results newest-first. - Optional bearer-token authentication; `/health` endpoint is always open for liveness checks. - No state, message store, or per-provider client library required—uses Python stdlib and FastAPI. - Supports granular mailbox operations, full structured search, and simple per-mailbox requests.","fileCount":3,"zipByteSize":9736}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17fq93tmpky791n7516jcn08n83sfn2:docker-mailbox","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17fq93tmpky791n7516jcn08n83sfn2:docker-mailbox` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/psyb0t/docker-mailbox before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T00:31:38.495Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-psyb0t-docker-mailbox/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T22:17:22.290Z","emptyReason":null},"readme":"Skill: docker-mailbox\n\nOwner: psyb0t\n\nSummary: Multi-mailbox IMAP/SMTP control plane exposed as a REST API + MCP server (streamable HTTP) on a single port. Read, search, send, mark-seen, and delete mail across multiple inboxes in one call — `GET /inbox` fans out across every IMAP account in parallel and returns a merged, newest-first feed. Use when you need an agent (or a script, or a curl one-liner) to drive one or more real mail accounts without standing up a webmail UI, a message store, or any per-provider client library. Stdlib `imaplib`/`smtplib` under the hood, FastAPI on top, bearer-token auth optional.\n\nTags: latest:1.2.3\n\nVersion history:\n\nv1.2.3 | 2026-08-20T14:39:02.946Z | auto\n\n- Updated setup and reference documentation in `references/setup.md`.\n- Removed redundant `skill-card.md` file.\n- No user-facing functionality changes; documentation cleanup only.\n\nv1.2.2 | 2026-07-26T02:23:49.158Z | auto\n\ndocker-mailbox 1.2.2\n\n- Updated SKILL.md language for improved clarity and conciseness, especially in security warnings and deletion guidance.\n- Expanded search example in `/inbox` documentation to include searching a specific folder.\n- Removed old skill-card.md file.\n- No functional or API changes; documentation only.\n\nv1.2.1 | 2026-07-26T01:34:29.493Z | auto\n\n- Added a \"Security & safety\" section to the documentation, detailing important warnings about destructive deletes, authentication/config best practices, and data handling.\n- Removed the file skill-card.md from the project.\n- No changes to functionality or API; changes are documentation and file organization only.\n\nv1.2.0 | 2026-05-18T04:23:22.707Z | user\n\nNo visible file changes detected for version 1.2.0. No changes to functionality or documentation.\n\nv1.1.0 | 2026-05-18T03:31:38.641Z | user\n\nNo file changes detected for this release.\n\n- No user-facing changes or updates in this version.\n- Functionality and documentation remain the same as the previous release.\n\nv1.0.0 | 2026-05-18T03:17:43.482Z | user\n\ndocker-mailbox v1.0.0\n\n- Initial release providing a unified REST API and MCP server for controlling multiple IMAP/SMTP mailboxes on a single port.\n- Supports reading, searching, sending, marking as seen, and deleting mail across multiple inboxes in one call.\n- Unified `GET /inbox` endpoint fans out searches across all configured mailboxes and merges results newest-first.\n- Optional bearer-token authentication; `/health` endpoint is always open for liveness checks.\n- No state, message store, or per-provider client library required—uses Python stdlib and FastAPI.\n- Supports granular mailbox operations, full structured search, and simple per-mailbox requests.\n\nArchive index:\n\nArchive v1.2.3: 4 files, 12822 bytes\n\nFiles: references/setup.md (10629b), skill-card.md (2675b), SKILL.md (17810b), _meta.json (133b)\n\nFile v1.2.3:SKILL.md\n\n---\nname: docker-mailbox\ndescription: Multi-mailbox IMAP/SMTP control plane exposed as a REST API + MCP server (streamable HTTP) on a single port. Read, search, send, mark-seen, and delete mail across multiple inboxes in one call — `GET /inbox` fans out across every IMAP account in parallel and returns a merged, newest-first feed. Use when you need an agent (or a script, or a curl one-liner) to drive one or more real mail accounts without standing up a webmail UI, a message store, or any per-provider client library. Stdlib `imaplib`/`smtplib` under the hood, FastAPI on top, bearer-token auth optional.\ncompatibility: Requires curl and a running mailboxd instance. MAILBOX_URL env var must be set. MAILBOX_TOKEN is optional — only needed if the server was started with `auth.tokens` configured.\nmetadata:\n author: psyb0t\n homepage: https://github.com/psyb0t/docker-mailbox\n---\n\n# docker-mailbox\n\nREST + MCP shim over IMAP/SMTP. Point it at one or more mail accounts via a YAML config, get back **one HTTP API + one MCP server on the same port** (MCP rides a streamable-HTTP endpoint at `/mcp`). No webmail. No DB. No message store. Stateless — restart it and nothing's lost because nothing was ever kept.\n\nThe killer endpoint is `GET /inbox` — it hits every IMAP account in parallel, runs the same structured search on each, merges newest-first, and tags every result with which mailbox it came from. \"Show me everything from `boss@corp.com`,\" \"what's unread right now,\" \"what came in this morning\" — one call, no fanout dance on the client side.\n\nFor installation and setup, see [references/setup.md](references/setup.md).\n\n## Security & safety\n\n- **Deleting mail is permanent** — the delete endpoint flags a message `\\Deleted` and `EXPUNGE`s it immediately (no trash bin, no undo). Only delete specific message UIDs the user has confirmed; never bulk-delete straight from a broad `/inbox` or `/search` result — list first, show what matched, confirm, then delete. On a multi-mailbox instance, always confirm which `mailbox`/UID you're targeting so you don't touch the wrong account.\n- **No auth when `auth.tokens` is empty.** With it unset the HTTP API AND `/mcp` are UNAUTHENTICATED — anyone who can reach the port gets full read/send/delete access to every configured mailbox. NEVER expose such an instance on a network or to untrusted agents; set `auth.tokens` and bind to loopback / behind an authenticating proxy.\n- **Every call sends your mail data to whatever `MAILBOX_URL` points at.** Point it only at a `mailboxd` instance you run or explicitly trust; prefer HTTPS if it's reachable over a network.\n\n## Setup\n\nThe API should already be running. Set the base URL and (if configured) the bearer token:\n\n```bash\nexport MAILBOX_URL=http://localhost:8000\nexport MAILBOX_TOKEN=your_token_here # omit if auth.tokens is empty in config\n```\n\n**Verify:**\n\n```bash\ncurl -s $MAILBOX_URL/health\n# {\"ok\": true, \"version\": \"0.1.0\"}\n\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" $MAILBOX_URL/mailboxes | jq\n```\n\n`/health` is **always open** — point liveness probes at it without worrying about auth.\n\nAuth is optional. If `auth.tokens` is empty/missing in the server config, all endpoints are open. If it's set, every non-`/health` request needs `Authorization: Bearer ` and returns `401` (with `WWW-Authenticate: Bearer`) on miss. Tokens are constant-time compared. The same gate covers `/mcp`.\n\n## How It Works\n\n`GET` to read, `POST` to send/mark/create, `DELETE` to delete. All bodies are JSON. All responses are JSON.\n\nEvery error response:\n\n```json\n{\"detail\": \"description of what went wrong\"}\n```\n\nStatus codes:\n\n| Status | When |\n| ------ | ------------------------------------------------------------------------------------------ |\n| `401` | Missing or invalid bearer (when auth is on). |\n| `404` | Unknown mailbox name in the URL. |\n| `409` | Mailbox doesn't have the requested protocol (IMAP endpoint on an SMTP-only mailbox). |\n| `422` | Request body validation failed (pydantic). |\n| `502` | The IMAP / SMTP server upstream rejected the operation. |\n\nUIDs (not sequence numbers) are used for every message identifier so IDs stay stable across server-side mutations.\n\n## API Reference\n\n### Health\n\n```bash\ncurl -s $MAILBOX_URL/health\n# {\"ok\": true, \"version\": \"0.1.0\"}\n```\n\n### Mailboxes\n\n```bash\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" $MAILBOX_URL/mailboxes\n```\n\n```json\n{\n \"mailboxes\": [\n { \"name\": \"personal\", \"description\": \"Gmail\", \"imap\": true, \"smtp\": true },\n { \"name\": \"work\", \"description\": \"\", \"imap\": true, \"smtp\": true }\n ]\n}\n```\n\n`name` is the URL-safe handle (matches `[a-zA-Z0-9_-]+`, unique) used in every other path. The `imap` / `smtp` booleans tell you which protocols the server has configured for that mailbox — if `imap: false`, you can't list/fetch/delete; if `smtp: false`, you can't send.\n\n### Unified inbox (the main read endpoint)\n\n`GET /inbox` fans out across **every IMAP-configured mailbox** in parallel, runs the same structured search against each one, merges newest-first, and tags each message with which account it came from. Per-mailbox failures land in `errors` instead of aborting the whole call.\n\n| Query param | What it does |\n| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |\n| `mailbox` | CSV filter by mailbox name (`personal`) **or** email address (`me@gmail.com`). Omit to search all IMAP mailboxes. |\n| `from`, `to`, `subject`, `body`, `text` | IMAP SEARCH predicates. `text` is full-text across headers + body. |\n| `since`, `before` | IMAP date filters, e.g. `1-Jan-2026`. |\n| `unseen`, `seen`, `flagged`, `answered` | Boolean flag filters. |\n| `larger_than`, `smaller_than` | Size filters in bytes. |\n| `folder` | IMAP folder name (default `INBOX`). |\n| `limit` | Max merged results, ≤ 500 (default 50). |\n\n```bash\n# everything from one sender, all accounts\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/inbox?from=boss@corp.com&limit=20\" | jq\n\n# unread mail in just two accounts\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/inbox?mailbox=personal,work&unseen=true\" | jq\n\n# everything since yesterday, full-text \"invoice\"\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/inbox?since=$(date -d 'yesterday' +%-d-%b-%Y)&text=invoice\" | jq\n\n# search a specific folder (e.g. Spam)\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/inbox?folder=Spam&limit=10\" | jq\n```\n\nResponse:\n\n```json\n{\n \"messages\": [\n {\n \"uid\": \"1234\",\n \"mailbox\": \"personal\",\n \"mailbox_address\": \"me@gmail.com\",\n \"from\": \"boss@corp.com\",\n \"to\": \"me@gmail.com\",\n \"subject\": \"weekly sync\",\n \"date\": \"Mon, 18 May 2026 09:15:00 +0000\",\n \"message_id\": \"<...@corp.com>\",\n \"flags\": [\"\\\\Seen\"]\n }\n ],\n \"errors\": [\n { \"mailbox\": \"work\", \"error\": \"login failed: ...\" }\n ]\n}\n```\n\n### Per-mailbox IMAP\n\nWhen you want to target one account directly:\n\n```bash\n# Folders\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n $MAILBOX_URL/mailboxes/personal/folders\n\n# List newest-first headers — raw IMAP SEARCH criteria\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/mailboxes/personal/messages?folder=INBOX&limit=20&search=UNSEEN\"\n\n# Structured single-mailbox search — same query params as /inbox minus `mailbox`\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/mailboxes/personal/search?from=boss@corp.com&since=1-May-2026\"\n\n# Fetch one full message (decoded body_text + body_html + attachment metadata)\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX\"\n\n# Same but also get `body_reader` — HTML stripped to clean text/markdown\n# (perfect for feeding into an LLM without all the table/style chrome)\ncurl -s -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX&reader=true\"\n\n# Mark seen / unseen\ncurl -s -X POST -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n -H 'Content-Type: application/json' \\\n -d '{\"seen\": true}' \\\n \"$MAILBOX_URL/mailboxes/personal/messages/1234/seen?folder=INBOX\"\n\n# Delete (flag \\Deleted + EXPUNGE — gone, really gone)\ncurl -s -X DELETE -H \"Authorization: Bearer $MAILBOX_TOKEN\" \\\n \"$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX\"\n```\n\n`DELETE /mailboxes//messages/` permanently removes a message (`\\Deleted` + `EXPUNGE`, no undo). Confirm the target `mailbox`/UID first — see [Security & safety](#security--safety).\n\n`/messages` `search` is **raw IMAP SEARCH** (e.g. `ALL`, `UNSEEN`, `FROM foo@bar`, `(UNSEEN FROM foo@bar)`). `/search` is the structured query DSL — same params as `/inbox` minus `mailbox`. Use whichever's easier.\n\nFull-message fetch returns:\n\n```json\n{\n \"uid\": \"1234\",\n \"from\": \"boss@corp.com\",\n \"to\": \"me@gmail.com\",\n \"cc\": \"\",\n \"subject\": \"weekly sync\",\n \"date\": \"Mon, 18 May 2026 09:15:00 +0000\",\n \"message_id\": \"<...@corp.com>\",\n \"body_text\": \"plain text body\",\n \"body_html\": \"

html body

\",\n \"body_reader\": null,\n \"attachments\": [\n {\"filename\": \"agenda.pdf\", \"content_type\": \"application/pdf\", \"size\": 12345}\n ]\n}\n```\n\n`body_reader` is `null` unless you pass `reader=true`. When enabled it falls back to `body_text` if no HTML body exists, otherwise it's the HTML body stripped to readable markdown (links inline, images dropped, tables flattened, no styles/scripts).\n\n#### How reader mode works\n\nRuns the HTML body through [html2text](https://github.com/Alir3z4/html2text) configured for LLM consumption: `body_width=0` (no wrap), `ignore_images=True` (kills `` tracking pixels), `unicode_snob=True` (real unicode, no smart-quote mangling). `