# ai.spideriq/mail (npm · @spideriq/mcp-mail)

SpiderIQ Mail: SpiderMail mailboxes, messages, threads, send, compose for AI agents

- Trust score: 63/100 (medium)
- Change this week: +45
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@spideriq/mcp-mail`: 63/100 (this document), [markdown](https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail.md), [page](https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail)

## Channel facts

- Registry: `npm`
- Package: `@spideriq/mcp-mail`
- Version: `1.4.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (100 of 104), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (100 of 104), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 19/100
  - Repository check failed: the declared repository URL returned HTTP 404.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 7 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 71/100
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 4522 tokens (~77/item across 58 items; 58 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add ai-spideriq-mail -- npx -y @spideriq/mcp-mail
```

### Codex

```bash
codex mcp add ai-spideriq-mail -- npx -y @spideriq/mcp-mail
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ai-spideriq-mail": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@spideriq/mcp-mail"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add ai-spideriq-mail --command npx --arg -y --arg @spideriq/mcp-mail
```

### Hermes

```yaml
mcp_servers:
  ai-spideriq-mail:
    command: "npx"
    args: ["-y", "@spideriq/mcp-mail"]
```

### Other

```json
{
  "mcpServers": {
    "ai-spideriq-mail": {
      "command": "npx",
      "args": [
        "-y",
        "@spideriq/mcp-mail"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 63, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 59, +43)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → good
- [functional] Licence: MIT

### 2026-08-01 (score 16, −6)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 22, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-28 (score 40, +22)

- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: pass
- [functional] First check of Schema quality: unverified
- [functional] First check of Tool coverage: 100

### 2026-07-27 (score 18)

First indexed and scored.

## MCP tools (58)

### `request_access` (~120 tokens)

Request access to SpiderIQ API. This sends an approval email to the admin.
After calling this, use check_access_status to poll for approval.
Once approved, the token is automatically saved for subsequent API calls.

Input parameters:

- `api_url` (string): API URL (default: https://spideriq.ai)
- `email` (string, required): Admin email address (the person who will approve access)
- `project` (string): Project name (shown in approval email)
- `scopes` (array): Requested permission scopes (default: jobs:submit, jobs:read)

### `check_access_status` (~152 tokens)

Check the status of a PAT access request.
Returns 'pending', 'active', 'denied', 'expired', or 'revoked' (matches the
backend PATRequestStatus enum). Once status==='active', the token is saved to
\~/.spideriq/credentials.json automatically. Multi-brand approvals save one
entry per workspace under client_id, with the first aliased as 'default' so
existing tools (upload_local_file, etc.) keep working without --workspace.

Input parameters:

- `api_url` (string): API URL (default: https://spideriq.ai)
- `poll_token` (string, required): Poll token from request_access
- `request_id` (string, required): Request ID from request_access

### `get_auth_status` (~33 tokens)

Check if you are authenticated and get current user info.

Input parameters:

- `workspace` (string): Workspace name (default: default)

### `logout` (~25 tokens)

Remove stored authentication credentials.

Input parameters:

- `workspace` (string): Workspace name (default: default)

### `list_workspaces` (~19 tokens)

List all configured workspaces and their authentication status.

### `health_check` (~51 tokens)

Check if the SpiderIQ API is healthy and responsive.

Input parameters:

- `api_url` (string): API URL (default: https://spideriq.ai)
- `workspace` (string): Workspace name (default: default)

### `get_queue_stats` (~48 tokens)

Get statistics about job queues (pending jobs, consumers, etc.).

Input parameters:

- `format` (string): Response format (default: json)
- `workspace` (string): Workspace name (default: default)

### `get_api_info` (~33 tokens)

Get information about the SpiderIQ API and your connection.

Input parameters:

- `workspace` (string): Workspace name (default: default)

### `list_mailboxes` (~42 tokens)

List your SpiderMail mailboxes.

Input parameters:

- `format` (string): Response format (default: json)
- `workspace` (string): Workspace name (default: default)

### `list_messages` (~100 tokens)

List messages in a mailbox.

Input parameters:

- `format` (string): Response format (default: json)
- `mailbox_id` (string, required): Mailbox ID or email address
- `page` (number): Page number (default: 1)
- `per_page` (number): Results per page (default: 20)
- `unread_only` (boolean): Show only unread messages (default: false)
- `workspace` (string): Workspace name (default: default)

### `read_message` (~64 tokens)

Read a specific email message.

Input parameters:

- `format` (string): Response format (default: json)
- `mailbox_id` (string, required): Mailbox ID or email address
- `message_id` (string, required): Message ID
- `workspace` (string): Workspace name (default: default)

### `send_email` (~210 tokens)

Send, reply to, or forward an email through a registered mailbox.
Actions: send (new email), reply (respond to existing), forward (pass along).
Emails are sent via the SpiderMail worker queue.

Input parameters:

- `action` (string): Email action (default: send)
- `body_html` (string): HTML email body (optional)
- `body_text` (string, required): Plain text email body (required)
- `cc` (array): CC recipients
- `from_email` (string, required): Sender email (must be a registered mailbox)
- `reply_all` (boolean): Reply to all recipients (only for reply action)
- `reply_to_message_id` (number): Message ID to reply to (required for reply/forward)
- `subject` (string): Subject line (required for send)
- `test` (boolean): Route to test queue (default: false)
- `to` (array): Recipient email addresses (required for send/forward)
- `workspace` (string): Workspace name (default: default)

### `get_inbox` (~96 tokens)

Get inbox messages with optional filtering by mailbox, folder, and read status.

Input parameters:

- `folder` (string): Folder name (default: inbox)
- `limit` (number): Max results (default: 20)
- `mailbox` (string): Filter by mailbox email
- `offset` (number): Offset for pagination
- `unread_only` (boolean): Show only unread (default: false)
- `workspace` (string): Workspace name

### `search_mail` (~152 tokens)

Full-text search one mailbox (subject + body) + filters. `email` (the mailbox to search) is REQUIRED — there is no all-mailbox search.

Input parameters:

- `before` (string): Only messages before this ISO-8601 date
- `email` (string, required): Mailbox email address to search (required)
- `from` (string): Filter by sender address (substring)
- `limit` (number): Max results (default: 20)
- `query` (string, required): Full-text query over subject + body
- `since` (string): Only messages on/after this ISO-8601 date
- `subject` (string): Filter by subject (substring)
- `workspace` (string): Workspace name

### `get_thread` (~36 tokens)

Get a conversation thread with all related messages.

Input parameters:

- `thread_id` (string, required): Thread ID
- `workspace` (string): Workspace name

### `create_mailbox` (~205 tokens)

Connect a new email mailbox by its IMAP + SMTP credentials (passwords encrypted at rest). Needs both imap_* and smtp_*; use an app-specific password where the provider requires one (465=SSL, 587=STARTTLS).

Input parameters:

- `display_name` (string): Sender display name
- `email_address` (string, required): Mailbox email address
- `imap_host` (string, required): IMAP server hostname
- `imap_password` (string, required): IMAP password / app password
- `imap_port` (number): IMAP port (default 993)
- `imap_username` (string, required): IMAP login username
- `provider` (string, required): Email provider
- `smtp_host` (string, required): SMTP server hostname
- `smtp_password` (string, required): SMTP password / app password
- `smtp_port` (number): SMTP port (default 587)
- `smtp_username` (string, required): SMTP login username
- `workspace` (string): Workspace name

### `delete_mailbox` (~39 tokens)

Delete a mailbox and all its data.

Input parameters:

- `email` (string, required): Mailbox email address to delete
- `workspace` (string): Workspace name

### `test_mailbox` (~41 tokens)

Test a mailbox connection (IMAP/SMTP).

Input parameters:

- `email` (string, required): Mailbox email address to test
- `workspace` (string): Workspace name

### `compose_assist` (~135 tokens)

AI assistance for composing an email — drafts or transforms copy. Does NOT send.
action=write generates a new draft from context/subject; rewrite/expand/shorten/formal/casual/fix_grammar transform the text in "context".

Input parameters:

- `action` (string, required): AI action (default write)
- `context` (string): The brief (for write) or the text to transform
- `subject` (string): Email subject, for context
- `thread_context` (string): Previous thread messages for context
- `tone` (string): Desired tone (default professional)
- `workspace` (string): Workspace name

### `get_session` (~78 tokens)

One-call mailbox bootstrap: mailbox info + unread count + recent messages. Best first call for a mailbox.

Input parameters:

- `email` (string, required): Mailbox email address
- `format` (string): Response format
- `include_recent` (number): Recent messages to include (0-50, default 10)
- `workspace` (string): Workspace name

### `get_message` (~72 tokens)

Read one message by numeric id (marks it read). Includes attachment previews inline by default.

Input parameters:

- `format` (string): Response format
- `include_attachments` (boolean): Include attachment summaries + previews (default true)
- `message_id` (string, required): Numeric message id
- `workspace` (string): Workspace name

### `get_mailbox_stats` (~42 tokens)

Per-mailbox unread/starred/total counts plus client-wide totals.

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `list_folders` (~67 tokens)

List a mailbox's folders (INBOX/Sent/Drafts/Trash) with per-folder totals + unread counts. email is required.

Input parameters:

- `email` (string, required): Mailbox email address (required)
- `format` (string): Response format
- `workspace` (string): Workspace name

### `update_message` (~102 tokens)

Update a message flags — mark read/unread, star, set labels (labels REPLACE the set), private note.

Input parameters:

- `is_read` (boolean): Mark read/unread
- `is_starred` (boolean): Star/unstar
- `labels` (array): Replace the label set with this list
- `message_id` (string, required): Numeric message id
- `notes` (string): Private note (not sent)
- `workspace` (string): Workspace name

### `bulk_update_messages` (~89 tokens)

Apply one action to many messages (≤100 ids): mark_read | mark_unread | archive | delete | add_label. delete is irreversible; add_label needs label.

Input parameters:

- `action` (string, required): Bulk action
- `label` (string): Label name (required for add_label)
- `message_ids` (array, required): Message ids (1-100)
- `workspace` (string): Workspace name

### `snooze_message` (~68 tokens)

Hide a message from the inbox until an ISO-8601 timestamp, then auto-return it.

Input parameters:

- `message_id` (string, required): Numeric message id
- `snoozed_until` (string, required): ISO-8601 timestamp to unsnooze at
- `workspace` (string): Workspace name

### `unsnooze_message` (~43 tokens)

Cancel a snooze — return the message to the inbox now.

Input parameters:

- `message_id` (string, required): Numeric message id
- `workspace` (string): Workspace name

### `list_snoozed` (~44 tokens)

List messages currently snoozed (hidden until their unsnooze time).

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `release_message` (~50 tokens)

Release a quarantined message back into the inbox (only after a human judges it safe).

Input parameters:

- `message_id` (string, required): Numeric id of the quarantined message
- `workspace` (string): Workspace name

### `list_labels` (~49 tokens)

List label DEFINITIONS (name + colour). Applying a label to a message is update_message / bulk_update_messages.

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `create_label` (~65 tokens)

Define a new label (name ≤50 chars + hex colour #RRGGBB, default #6B7280).

Input parameters:

- `color` (string): Hex colour #RRGGBB
- `name` (string, required): Label name
- `workspace` (string): Workspace name

### `update_label` (~59 tokens)

Rename or recolour a label definition.

Input parameters:

- `color` (string): New hex colour #RRGGBB
- `label_id` (string, required): Label id
- `name` (string): New name
- `workspace` (string): Workspace name

### `delete_label` (~32 tokens)

Delete a label definition.

Input parameters:

- `label_id` (string, required): Label id
- `workspace` (string): Workspace name

### `list_views` (~44 tokens)

List saved inbox views (named filter bundles). Apply one via get_inbox view_id.

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `create_view` (~119 tokens)

Save a named inbox view from a filter_config ({mailboxes[], unread_only, starred_only, has_attachments}). is_shared exposes it team-wide.

Input parameters:

- `color` (string): Display colour
- `filter_config` (object): Filter config
- `is_shared` (boolean): Share with the whole client team
- `name` (string, required): View name (≤200 chars)
- `sort_by` (string): Sort field (default date)
- `sort_direction` (string): Sort direction (default DESC)
- `workspace` (string): Workspace name

### `get_view` (~51 tokens)

Get one saved view by id (its filter_config + display config).

Input parameters:

- `format` (string): Response format
- `view_id` (string, required): Saved view id
- `workspace` (string): Workspace name

### `update_view` (~97 tokens)

Edit a saved view (creator-only).

Input parameters:

- `color` (string): New colour
- `filter_config` (object): New filter config
- `is_shared` (boolean): Share with the team
- `name` (string): New name
- `sort_by` (string): Sort field
- `sort_direction` (string): Sort direction
- `view_id` (string, required): Saved view id
- `workspace` (string): Workspace name

### `delete_view` (~36 tokens)

Delete a saved view (creator-only).

Input parameters:

- `view_id` (string, required): Saved view id
- `workspace` (string): Workspace name

### `mail_list_templates` (~39 tokens)

List email templates (signature / header / layout / full).

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `mail_get_template` (~50 tokens)

Get one email template's source + detected variables by id.

Input parameters:

- `format` (string): Response format
- `template_id` (string, required): Integer template id
- `workspace` (string): Workspace name

### `mail_create_template` (~146 tokens)

Create a Jinja2 email template. template_type: signature | header | layout (has a {{ body }} slot) | full. Variables auto-detect.

Input parameters:

- `description` (string): Human description
- `html_source` (string, required): Jinja2 HTML source
- `is_default` (boolean): Set as default for this type
- `name` (string, required): Unique name ([a-z0-9-_], lowercased)
- `template_type` (string): Template type (default full)
- `text_source` (string): Optional plain-text variant
- `variables` (array): Variable names (auto-detected if omitted)
- `workspace` (string): Workspace name

### `mail_update_template` (~127 tokens)

Update an email template (any subset of fields).

Input parameters:

- `description` (string): New description
- `html_source` (string): New Jinja2 source
- `is_active` (boolean): Enable/disable
- `is_default` (boolean): Set as default for its type
- `name` (string): New name
- `template_id` (string, required): Integer template id
- `template_type` (string): Template type
- `text_source` (string): New plain-text variant
- `variables` (array): New variable list
- `workspace` (string): Workspace name

### `mail_delete_template` (~36 tokens)

Delete an email template by id.

Input parameters:

- `template_id` (string, required): Integer template id
- `workspace` (string): Workspace name

### `mail_preview_template` (~64 tokens)

Render a template with sample variables and return HTML WITHOUT sending. Use before a real send. Missing variables render empty.

Input parameters:

- `template_id` (string, required): Integer template id
- `variables` (object): Variable values for the render
- `workspace` (string): Workspace name

### `list_security_events` (~61 tokens)

List mail security events — inbound prompt-injection detections, outbound credential blocks, quarantines, releases.

Input parameters:

- `format` (string): Response format
- `limit` (number): Max events (default 50)
- `workspace` (string): Workspace name

### `list_quarantine` (~48 tokens)

List messages auto-quarantined by the inbound prompt-injection scanner (kept out of the inbox).

Input parameters:

- `format` (string): Response format
- `workspace` (string): Workspace name

### `list_outreach_connections` (~62 tokens)

List a brand's outreach sidecars (Smartlead/lemlist/Instantly): provider, workspace_id, warmup_tag, lemwarm_domains, active.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `workspace` (string): Workspace name

### `get_outreach_connection` (~63 tokens)

Get one outreach connection by id (provider, workspace_id, warmup_tag, lemwarm_domains, active).

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `workspace` (string): Workspace name

### `update_outreach_connection` (~196 tokens)

Edit an outreach connection (workspace_id / warmup_tag / lemwarm_domains / is_active / smartlead_client_id / max_active_leads). BRAND-ADMIN only.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `is_active` (boolean): Enable/pause the sidecar
- `lemwarm_domains` (array): lemlist warmup domains
- `max_active_leads` (number): Cap on distinct leads pushed via this connection (mirrors the SmartLead account lead-credit ceiling); 0+ or omit for uncapped
- `smartlead_client_id` (string): SmartLead agency/whitelabel client id (scopes shared-account campaigns); empty string clears it
- `warmup_tag` (string): Tag marking warmup sends
- `workspace` (string): Workspace name
- `workspace_id` (string): Provider workspace id

### `delete_outreach_connection` (~70 tokens)

Remove an outreach sidecar (cascades senders/campaigns/health; leaves the api_integrations credential). BRAND-ADMIN only.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `workspace` (string): Workspace name

### `sync_outreach_connection` (~61 tokens)

Pull latest sender accounts + warmup state from the provider into SpiderMail. BRAND-ADMIN only.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `workspace` (string): Workspace name

### `list_outreach_senders` (~55 tokens)

List every sending account across a brand's outreach connections (email, provider, warmup_enabled, status, mailbox_id).

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `workspace` (string): Workspace name

### `get_sender_health` (~78 tokens)

One sender's latest deliverability/warmup snapshot — health_score, sent/inbox/spam/bounce/reply (24h+7d), warmup_enabled, polled_at.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `sender_id` (string, required): Outreach sender id
- `workspace` (string): Workspace name

### `get_outreach_health_overview` (~56 tokens)

Latest health snapshot per sender for the whole brand — the deliverability/warmup grid for all sending accounts at once.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `workspace` (string): Workspace name

### `list_outreach_campaigns` (~82 tokens)

List the SmartLead campaigns this connection can see (scoped by its agency client_id) — use to pick a target before pushing leads. Returns remote_campaign_id, name, status, lead_count.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `workspace` (string): Workspace name

### `push_outreach_leads` (~188 tokens)

Push a SpiderIQ campaign's verified leads into a chosen SmartLead campaign. Idempotent (won't re-add). Returns added/skipped counts + account leads used. 409 if the per-account lead cap would be exceeded (pass `limit` to trim instead). BRAND-ADMIN only.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `limit` (number): Optional: add at most N new leads (also trims to the account cap instead of erroring)
- `remote_campaign_id` (string, required): Target SmartLead campaign id (from list_outreach_campaigns)
- `smartlead_campaign_name` (string): Optional target campaign name (for the confirmation notification)
- `spideriq_campaign_id` (string, required): Source SpiderIQ campaign id (its verified leads are pushed)
- `workspace` (string): Workspace name

### `remove_outreach_leads` (~136 tokens)

Remove tracked leads from a SmartLead campaign (frees account lead credits). Scope by spideriq_campaign_id and/or an explicit email list; with neither, removes ALL leads SpiderIQ pushed to that campaign. BRAND-ADMIN only.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `emails` (array): Optional: only remove these specific lead emails
- `remote_campaign_id` (string, required): Target SmartLead campaign id
- `spideriq_campaign_id` (string): Optional: only remove leads from this source campaign
- `workspace` (string): Workspace name

### `get_outreach_push_status` (~96 tokens)

Quota usage (active_leads / max_active_leads / available) + per-campaign push counts (pushed/skipped/removed) for a connection. Use to see how many leads are in each SmartLead campaign and how much account headroom is left.

Input parameters:

- `brand_id` (string, required): Numeric brand id
- `connection_id` (string, required): Outreach connection id
- `workspace` (string): Workspace name

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail#diagnostics

## Score history

- 2026-08-03: 63
- 2026-08-02: 59
- 2026-08-01: 16
- 2026-07-31: 22
- 2026-07-29: 40
- 2026-07-28: 40
- 2026-07-27: 18

## Links

- npm package: https://www.npmjs.com/package/@spideriq/mcp-mail
- Socket report: https://socket.dev/npm/package/@spideriq/mcp-mail
- Changelog RSS feed: https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail/changelog.json
- HTML version of this page: https://verifymcp.io/servers/ai-spideriq-mail/spideriq-mcp-mail