Integrations

docker-mailbox

Try it

Drive one or more IMAP/SMTP mailboxes through a single REST + MCP endpoint — read, search, send, mark-seen, and delete across accounts in parallel.

What it does

Point docker-mailbox at one or more mail accounts via YAML config and get a REST API plus an MCP server (streamable HTTP at /mcp) on the same port. `GET /inbox` fans out across every configured IMAP account in parallel, runs the same structured search on each, and returns a merged newest-first feed with each result tagged by which mailbox it came from. Read, search, send, mark seen/unseen, and delete (permanently — `\Deleted` + `EXPUNGE`, no trash bin) over real mail accounts without standing up a webmail UI, a message store, or per-provider client libraries; stdlib `imaplib`/`smtplib` underneath, FastAPI on top. Auth is optional — when `auth.tokens` is empty, every endpoint is unauthentica…

When to use it

  • Agent driving real mail accounts via MCP tools over streamable HTTP
  • Cross-account inbox search in a single HTTP call (no client-side fanout)
  • Sending mail from a script without a per-provider SDK
  • Feeding LLM-friendly markdown message bodies via `reader=true`

The skill document

docker-mailbox

REST + 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.

The 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.

For installation and setup, see references/setup.md.

Security & safety

  • Deleting mail is permanent — the delete endpoint flags a message \Deleted and EXPUNGEs 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.
  • 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.
  • 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.

Setup

The API should already be running. Set the base URL and (if configured) the bearer token:

export MAILBOX_URL=http://localhost:8000
export MAILBOX_TOKEN=your_token_here   # omit if auth.tokens is empty in config

Verify:

curl -s $MAILBOX_URL/health
# {"ok": true, "version": "0.1.0"}

curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" $MAILBOX_URL/mailboxes | jq

/health is always open — point liveness probes at it without worrying about auth.

Auth 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.

How It Works

GET to read, POST to send/mark/create, DELETE to delete. All bodies are JSON. All responses are JSON.

Every error response:

{"detail": "description of what went wrong"}

Status codes:

StatusWhen
401Missing or invalid bearer (when auth is on).
404Unknown mailbox name in the URL.
409Mailbox doesn't have the requested protocol (IMAP endpoint on an SMTP-only mailbox).
422Request body validation failed (pydantic).
502The IMAP / SMTP server upstream rejected the operation.

UIDs (not sequence numbers) are used for every message identifier so IDs stay stable across server-side mutations.

API Reference

Health

curl -s $MAILBOX_URL/health
# {"ok": true, "version": "0.1.0"}

Mailboxes

curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" $MAILBOX_URL/mailboxes
{
  "mailboxes": [
    { "name": "personal", "description": "Gmail", "imap": true, "smtp": true },
    { "name": "work",     "description": "",       "imap": true, "smtp": true }
  ]
}

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.

Unified inbox (the main read endpoint)

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.

Query paramWhat it does
mailboxCSV filter by mailbox name (personal) or email address (me@gmail.com). Omit to search all IMAP mailboxes.
from, to, subject, body, textIMAP SEARCH predicates. text is full-text across headers + body.
since, beforeIMAP date filters, e.g. 1-Jan-2026.
unseen, seen, flagged, answeredBoolean flag filters.
larger_than, smaller_thanSize filters in bytes.
folderIMAP folder name (default INBOX).
limitMax merged results, ≤ 500 (default 50).
# everything from one sender, all accounts
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?from=boss@corp.com&limit=20" | jq

# unread mail in just two accounts
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?mailbox=personal,work&unseen=true" | jq

# everything since yesterday, full-text "invoice"
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?since=$(date -d 'yesterday' +%-d-%b-%Y)&text=invoice" | jq

# search a specific folder (e.g. Spam)
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?folder=Spam&limit=10" | jq

Response:

{
  "messages": [
    {
      "uid": "1234",
      "mailbox": "personal",
      "mailbox_address": "me@gmail.com",
      "from": "boss@corp.com",
      "to": "me@gmail.com",
      "subject": "weekly sync",
      "date": "Mon, 18 May 2026 09:15:00 +0000",
      "message_id": "<...@corp.com>",
      "flags": ["\\Seen"]
    }
  ],
  "errors": [
    { "mailbox": "work", "error": "login failed: ..." }
  ]
}

Per-mailbox IMAP

When you want to target one account directly:

# Folders
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  $MAILBOX_URL/mailboxes/personal/folders

# List newest-first headers — raw IMAP SEARCH criteria
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/mailboxes/personal/messages?folder=INBOX&limit=20&search=UNSEEN"

# Structured single-mailbox search — same query params as /inbox minus `mailbox`
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/mailboxes/personal/search?from=boss@corp.com&since=1-May-2026"

# Fetch one full message (decoded body_text + body_html + attachment metadata)
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX"

# Same but also get `body_reader` — HTML stripped to clean text/markdown
# (perfect for feeding into an LLM without all the table/style chrome)
curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX&reader=true"

# Mark seen / unseen
curl -s -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"seen": true}' \
  "$MAILBOX_URL/mailboxes/personal/messages/1234/seen?folder=INBOX"

# Delete (flag \Deleted + EXPUNGE — gone, really gone)
curl -s -X DELETE -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/mailboxes/personal/messages/1234?folder=INBOX"

DELETE /mailboxes//messages/ permanently removes a message (\Deleted + EXPUNGE, no undo). Confirm the target mailbox/UID first — see Security & safety.

/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.

Full-message fetch returns:

{
  "uid": "1234",
  "from": "boss@corp.com",
  "to": "me@gmail.com",
  "cc": "",
  "subject": "weekly sync",
  "date": "Mon, 18 May 2026 09:15:00 +0000",
  "message_id": "<...@corp.com>",
  "body_text": "plain text body",
  "body_html": "html body",
  "body_reader": null,
  "attachments": [
    {"filename": "agenda.pdf", "content_type": "application/pdf", "size": 12345}
  ]
}

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).

How reader mode works

Runs the HTML body through 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)., , , comments and all inline-style chrome get dropped. Headings → #, bold/italic preserved, text → [text](x) inline, lists/tables converted to markdown equivalents.

The original body_text and body_html are still returned — body_reader is additive. UI clients can render HTML, agents can read markdown, attachments stay as metadata.

Useful when the text/plain part is missing or an auto-generated "view in HTML client" stub (which is true for most marketing/transactional mail). Limitations: reply-quote chains aren't stripped, table-layout emails come through as pipe-tables (faithful but visually noisy).

SMTP

curl -s -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "to":           ["dest@example.com"],
    "cc":           ["copy@example.com"],
    "bcc":          ["hidden@example.com"],
    "subject":      "hi",
    "body_text":    "plain text body",
    "body_html":    "optional html body",
    "from_address": "Me ",
    "reply_to":     "noreply@example.com"
  }' \
  $MAILBOX_URL/mailboxes/personal/send

Required: to (non-empty), subject, and at least one of body_text / body_html. Both bodies = multipart/alternative.

The SMTP client automatically sets Date, a domain-aligned Message-ID, and a Thunderbird-shaped User-Agent — provider spam filters get hostile when those are missing or sloppy, so we play the game. Response:

{
  "from":       "Me ",
  "to":         "dest@example.com",
  "subject":    "hi",
  "message_id": "<177906914784.1.7220590975517922818@example.com>"
}

MCP server

Same operations exposed as MCP tools over streamable HTTP at POST /mcp (same port, same bearer). One flat tool set — every per-mailbox op takes mailbox as a parameter (the configured name OR the email address), so the catalog stays constant-sized no matter how many accounts you configure:

mailboxes                   # discovery: list configured mailboxes + capabilities
inbox                       # unified read across all IMAP mailboxes (mailbox= filter)
list_folders                # (mailbox)
list_messages               # (mailbox, folder, limit, search)
search                      # (mailbox, from, subject, since, ...)
get_message                 # (mailbox, uid, reader=true → +body_reader)
delete_message              # (mailbox, uid)
mark_seen                   # (mailbox, uid, seen)
send                        # (mailbox, to, subject, body_text/html, ...)

Discovery flow for an agent: call mailboxes to see what's available, then pass the chosen name ("personal") or address ("me@gmail.com") as the mailbox argument. For cross-account reads use inbox — inbox(from="boss@corp.com") fans out across every IMAP-enabled mailbox in one call. IMAP-only tools only appear if at least one mailbox has IMAP; same for SMTP. No dead buttons.

There is no stdio transport. Point MCP clients at $MAILBOX_URL/mcp. The endpoint speaks the full streamable-HTTP protocol (GET opens SSE, POST sends requests, DELETE terminates the session). .mcp.json snippet:

{
  "mcpServers": {
    "mailbox": {
      "transport": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Drop the headers block if you're running without auth.tokens.

Common Workflows

Find and delete

Deletion is permanent (see Security & safety). Don't chain step 1 into step 2 automatically: run step 1 (list-only), show the matched mailbox/uid/from/subject to the user, get explicit confirmation of which UIDs to remove, then run step 2. A loose from/subject/text filter can match more than intended, so never remove every hit from a broad search unseen.

# 1. Find UIDs matching the criteria (dry-run: list only, delete nothing yet)
HITS=$(curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?from=newsletter@spam.io&limit=500" | jq -r '.messages[] | "\(.mailbox) \(.uid) \(.subject)"')
echo "$HITS"   # <-- review/confirm with the user before deleting anything

# 2. Only after explicit user confirmation of the specific UIDs above,
#    delete each (per-mailbox endpoint since DELETE is single-mailbox)
echo "$HITS" | while read -r mailbox uid _subject; do
  curl -s -X DELETE -H "Authorization: Bearer $MAILBOX_TOKEN" \
    "$MAILBOX_URL/mailboxes/$mailbox/messages/$uid"
done

Send-to-self e2e sanity check

MARKER="e2e-$(uuidgen | cut -c1-8)"

# 1. Send marker to self
curl -s -X POST -H "Authorization: Bearer $MAILBOX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"to\": [\"me@gmail.com\"], \"subject\": \"ping $MARKER\", \"body_text\": \"$MARKER\"}" \
  "$MAILBOX_URL/mailboxes/personal/send"

# 2. Search for it (may take a few seconds to land)
for i in 1 2 3 4 5; do
  sleep 2
  FOUND=$(curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
    "$MAILBOX_URL/inbox?subject=$MARKER" | jq -r '.messages | length')
  [ "$FOUND" -gt 0 ] && break
done

Pull unread across everything, format for a digest

curl -s -H "Authorization: Bearer $MAILBOX_TOKEN" \
  "$MAILBOX_URL/inbox?unseen=true&limit=100" \
  | jq -r '.messages[] | "\(.mailbox)\t\(.from)\t\(.subject)"' \
  | column -t -s $'\t'

Tips

  • Date filters (since, before) use IMAP date format (1-Jan-2026), not ISO — date -d ... +%-d-%b-%Y is your friend.
  • larger_than / smaller_than are in bytes.
  • folder defaults to the mailbox's default_folder (usually INBOX). Provider-specific folder names: Gmail = [Gmail]/Spam, GMX/Yahoo = Spam, Outlook = Junk Email. Use GET /mailboxes//folders to discover.
  • A self-send may land in Spam on some providers (GMX especially) due to provider-side self-send heuristics even with proper headers — search folder=Spam if you don't see it in INBOX.
  • Gmail / Yahoo / etc. need app passwords, not your account password. Generate one in the provider's security settings.
  • delete is a real EXPUNGE — there is no trash bin equivalent unless the server moves to a Trash folder first. If you want soft delete, MOVE first then delete; mailboxd doesn't expose move yet.
  • Per-mailbox blowups in /inbox come back in the errors array — always check it, one dead account shouldn't blind you to the rest.
  • Bearer tokens live in the server's config.yaml under auth.tokens — list with multiple tokens to rotate without downtime.

Related skills

Generate and edit Draw.io, Mermaid, and Excalidraw diagrams from natural language using a structured JSON spec.

by nssa.io1.0k installs47 stars

Stores durable facts in a categorized, plain-markdown vault on disk, alongside your agent's built-in memory.

by Iván561 installs18 stars

Find why your productivity system keeps failing, then apply the smallest fix — capacity math, bottleneck routing, durable local notes.

by Iván855 installs69 stars

Join a video meeting as an AI bot with voice, avatar, and screenshare across four operating modes.

by johnpatternai22 installs8 stars

Fetch raw ad creative, app, ranking, and revenue data from AdMapix as structured JSON.

by fly0pants4.3k installs296 stars

More from psyb0t

Browse all skills

Drive a user-deployed mt5-httpapi MetaTrader 5 bridge over HTTP, with per-action confirmation on every real-money call.

by psyb0t108 installs4 stars

Docker-packaged browser automation for QA against anti-bot stacks and authorized detection testing.

by psyb0t137 installs2 stars

Self-hosted OpenAI-compatible speech service — transcription, translation, and synthesis from one container.

by psyb0t13 installs

Run ffmpeg, sox, and ImageMagick jobs against your files in a fixed-allowlist SSH sandbox.

by psyb0t71 installs

Generate speech audio via Qwen3-TTS over SSH with preset voices, voice cloning, and voice design.

by psyb0t55 installs

Connect to a user-deployed audiolla server to perform stem separation, mastering, MIR analysis, DSP transforms, and loudness normalization on audio files.

by psyb0t15 installs