SpiderMail

Reading Your Inbox

Reading mail is synchronous — a single API call returns your messages. You can list one mailbox's inbox, list a unified inbox across every mailbox, open a full message, and follow a conversation thread. Adding ?format=yaml returns clean, low-token YAML, the default for AI agents.

List an inbox

GET /mail/inbox returns recent messages. Scope it to one mailbox with email, or omit email for the Master Inbox across every mailbox in your workspace.

# One mailbox
curl "https://spideriq.ai/api/v1/mail/inbox?email=alice@yourcompany.com&unread_only=true&format=yaml" \
  -H "Authorization: Bearer $TOKEN"

# Master Inbox — every mailbox
curl "https://spideriq.ai/api/v1/mail/inbox?format=yaml" \
  -H "Authorization: Bearer $TOKEN"

Useful query params:

  • email — scope to a single mailbox (omit for Master Inbox).

  • unread_only — true to show only unread.

  • folder — INBOX (default), Sent, Drafts, or Trash.

  • direction — inbound or outbound.

  • limit / offset — page through results (limit 1–100, default 20).

  • view_id — apply a saved view's filters.

  • format — json (default) or yaml.

From the CLI:

spideriq mail list alice@yourcompany.com --unread --format yaml

Open a message

Fetch a single message by its id. Opening a message marks it read.

curl "https://spideriq.ai/api/v1/mail/messages/5678?format=yaml" \
  -H "Authorization: Bearer $TOKEN"

The response carries the from/to/cc, subject, both body parts, flags, labels, and any attachment summaries. Pass include_attachments=false to omit attachment text, or spideriq mail read alice@yourcompany.com 5678 from the CLI.

Threads

A conversation is a thread. Fetch every message in one with its thread_id:

curl "https://spideriq.ai/api/v1/mail/threads/THREAD_ID?format=yaml" \
  -H "Authorization: Bearer $TOKEN"

SpiderMail computes thread_id from standard email headers, so a reply chain stays grouped just like it would in an email client. To continue a thread, reply with the reply action.

Mark read, star, label, and annotate

PATCH /mail/messages/{id} updates the flags you control on a message:

curl -X PATCH "https://spideriq.ai/api/v1/mail/messages/5678" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "is_starred": true, "labels": ["hot-lead"], "notes": "Wants a demo Thursday" }'

You can set is_read, is_starred, labels (an array), and a private notes string. To act on many messages at once, see bulk actions.

Agent bootstrap in one call

For an agent starting a session, GET /mail/session?email=… returns the mailbox info, unread count, and a slice of recent messages in a single request — a fast, low-token way to orient before working the inbox. Add format=yaml and an include_recent count (0–50).

curl "https://spideriq.ai/api/v1/mail/session?email=alice@yourcompany.com&include_recent=10&format=yaml" \
  -H "Authorization: Bearer $TOKEN"

Tip: format=yaml strips the tracking pixels, inline styles, and nested tables that bloat raw HTML email — an agent processes the same message in a fraction of the tokens. Make it your default for any read call.

Next steps

  1. Search across a mailbox.

  2. Organize with labels, snooze, and saved views.

  3. Read endpoints in the API Reference.