45 Methods, One Skill: How We Taught Agents to Run SpiderMail

Your agent could already call SpiderMail. What it couldn't do was use it well.

The MCP gave it 46 tools. But a pile of tools is not the same as knowing the workflow — when a 201 means "queued" and not "sent," that a reply threads on a numeric message id and not the RFC Message-ID, that asking for the inbox with no mailbox returns every mailbox. So we shipped the missing half: a four-layer agent skill — @spideriq/mail-skills — that wraps the tools in recipes. And there are a lot of recipes.

One surface, 45 methods, three traps it teaches

The skill declares 45 methods, every one mapped to a route we verified is actually served. But the value isn't the list — it's the references/ directory, where each workflow is written out as WRONG → RIGHT with real values:

• queued ≠ sent. A send is an async job. sendEmail returns a job_id; the SMTP send happens in a worker seconds later and can still fail at the gateway. The recipe makes the agent poll the job before it ever tells a human "done." (No email API you know does this — Resend, Postmark, SendGrid all return synchronously. The skill encodes the difference instead of letting the agent learn it in production.)

• The Master Inbox. getInbox with no email is all mailboxes, newest-first — not a default mailbox. One call, every conversation, across hundreds of inboxes.

• Attachments are a preview. Extracted text rides inline on getMessage; there is no separate fetch. The recipe tells the agent to work from the preview and say so when it's truncated.

Read, write, organize — and warm up

The 45 methods cover the whole lifecycle an SDR actually runs: read (session bootstrap, threads, full-text search, master inbox), send/reply/forward in markdown that renders to clean HTML, and the unglamorous inbox hygiene that keeps a fleet sane — bulk-triage up to 100 messages in a call, snooze, labels, saved views, Jinja2 templates you preview before a single send.

And then the part most "email for AI" stories skip: deliverability. The skill speaks to your Smartlead, lemlist, and Instantly connections — warmup state, inbox-vs-spam, bounce and reply rates, per-sender health — so the same agent that writes the reply can also tell you whether the mailbox sending it is healthy.

Author once, ship everywhere

The skill is one folder — SKILL.md router + client/schema.yaml envelope + references/ recipes + learnings/. From it, the same 45 capabilities reach every surface: the @spideriq/mcp-mail MCP server (54 tools), the spideriq mail CLI (46 subcommands), and the OPVS Marketplace — so Claude, Cursor, and an OPVS agent fleet all speak it identically.

One agent or a thousand. One mailbox or hundreds. The tools were always there. Now your agent has the playbook.