Search...

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.

  • include_body — true to get each message's full body inline instead of a 200-character preview. Defaults to false, and only takes effect together with format=yaml.

  • format — json (default) or yaml.

From the CLI:

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

Read a whole page of mail in one call

By default a list row carries only a short preview, so reading ten messages meant eleven requests. include_body=true with format=yaml returns every full body inline:

curl "https://spideriq.ai/api/v1/mail/inbox?include_body=true&format=yaml" \
  -H "Authorization: Bearer $SPIDERIQ_PAT"

Each message then carries the body envelope described below.

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.

The body envelope — an empty body always explains itself

Under format=yaml, the body arrives with its provenance attached rather than as a bare string:

::table
Field | Meaning
body | The body you should read — the plain-text part, or markdown converted from the HTML part
body_source | Why the body is what it is (see below)
size_original | Bytes of the source part
size_normalized | Bytes of the body actually returned
rfc822_message_id | The message's RFC Message-ID header

body_source is the point of the envelope:

::table
body_source | Meaning
text/plain | Served from the message's stored plain-text part
converted | The HTML part was converted to markdown for you
none | The message genuinely has no body
html_too_large | The HTML exceeded the per-message conversion limit
html_not_converted | This request's shared conversion budget was already used by earlier messages

So an empty body is never ambiguous. none means there was nothing to read; html_too_large and html_not_converted mean we declined the work — and in the second case you can simply request that message on its own to get it converted.

The envelope appears under format=yaml only. The JSON response returns the plain message shape without these fields.

Reading a thread works the same way, except the whole thread shares one conversion budget — so a long thread of large HTML messages can legitimately return html_not_converted on its later messages.

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.