Email Archive
Autonomous, searchable archives over the user's OWN mail — inbox, newsletters, senders, past correspondence. Two routes, pick deliberately. (1) CONTEXTS are the recommended entry point for anything topic-shaped ("what did these newsletters cover", "catch me up on X"): context-list → context-match → context-feed returns a ready-made digest — rolling summary plus the relevant messages — in one call, at a fraction of the tokens. (2) SEARCH is the per-message route for finding one specific mail: list-archives → search → get-message. Reaching for search + get-message on a topic question works but is the expensive path. Archives are created by linking mailboxes (local or external) as sources.
Endpoints (13)
List archives with their source counts. Optionally filter by owner email.
| Field | Type | Required | Description |
|---|---|---|---|
owner_email |
string | No | Filter archives by owner email. |
Search within one archive. Modes: keyword (full-text), semantic (meaning-based), hybrid (both merged). Combine a text query with optional filters (sender, folder, date range, attachments). Returns message metadata (no body) ordered by relevance or date. Each hit carries date_sent_iso and date_received_iso (ISO-8601 UTC) next to the raw unix values, plus snippet and snippet_source. snippet_source is "highlight" when the query matched the message body (matches are wrapped in **markdown bold**, never HTML), "excerpt" for the leading body text (semantic/hybrid and filter-only searches), or null when the message has no plain-text body at all — HTML-only mail, which is common for newsletters and notifications — in which case snippet is null too. Messages marked as handled are hidden by default — replies are detected automatically from the Sent folder — so pass include_done=true to see everything.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive to search within (tenant scope). |
query |
string | No | Full-text query over subject, body, recipients and attachment names. Empty = filter only. |
mode |
string | No | keyword (default, full-text), semantic (meaning-based, embedded messages only), or hybrid (both merged — best recall). |
from_email |
string | No | Filter by exact sender email. |
folder |
string | No | Filter by IMAP folder (e.g. "INBOX"). |
has_attachments |
integer | No | 1 = only messages with attachments, 0 = only without. |
include_done |
boolean | No | Include messages marked as handled. A message counts as handled once a reply to it is found in the Sent folder, or when the user marked it manually. Hidden by default; true shows everything. |
date_from |
string | No | Only messages received on/after this date (ISO date or unix timestamp). |
date_to |
string | No | Only messages received on/before this date (ISO date or unix timestamp). |
sort |
string | No | relevance (default), newest, or oldest. |
limit |
integer | No | Results per page (default 20, max 100). |
offset |
integer | No | Pagination offset (default 0). |
snippet |
integer | No | 0 = return no snippets at all (marginally faster). Default 1. |
snippet_chars |
integer | No | Snippet length in characters (default 200). Out-of-range values are clamped, not rejected. 0 also disables snippets. |
Fetch ONE archived message in full (incl. body) by its archive doc id or message_id. Scoped to the given archive. Use this when you need one specific mail verbatim — not to assemble a topic overview. Bodies are returned whole and can run to 100k+ characters (newsletters and threaded replies especially), so calling this in a loop over search results will exhaust the context window; use search snippets or context-feed for breadth and get-message only for depth. Body text is in body_plain; date_sent_iso and date_received_iso carry the ISO-8601 UTC form of the unix timestamps.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the message belongs to (tenant scope). |
id |
integer | No | Archive doc id (from a search result). Either id or message_id is required. |
message_id |
string | No | RFC Message-ID. Either id or message_id is required. |
List the attachments of one archived message. Returns index (a stable position in the MIME tree), filename, content_type and size_bytes per attachment. Use the index with the download endpoint to fetch the bytes. Embedded images that the message body references inline (signature logos) are hidden by default; pass include_hidden to see them. Read-only, does not touch the stored original.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the message belongs to (tenant scope). |
id |
integer | No | Archive doc id (from a search result). Either id or message_id is required. |
message_id |
string | No | RFC Message-ID. Either id or message_id is required. |
include_hidden |
boolean | No | Also return parts hidden by default (inline images referenced from the body, quoted HTML fragments). Each item carries hidden_by_default so the caller can tell them apart. |
Mark one message as handled, kept or needing action. Handled messages are hidden from search results by default. Replies are detected automatically from the Sent folder, so this endpoint is for corrections and for the two flags that cannot be derived. Only the flags you pass are changed; the others keep their current value. A manual choice here always wins over the automatic detection and will not be overwritten by it.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the message belongs to (tenant scope). |
id |
integer | No | Archive doc id (from a search result). Either id or message_id is required. |
message_id |
string | No | RFC Message-ID. Either id or message_id is required. |
done |
boolean | No | Handled — hide from the overview. Set false to bring a message back. |
keep |
boolean | No | Keep — protect from cleanup. Independent of done. |
todo |
boolean | No | Needs action. Independent of done and keep; a message can be both kept and pending. |
Draft a reply to one archived message. Returns suggested reply text only — it does not send anything, and the archive itself is never modified. The draft is generated from the message body; it does not invent facts, and when the message alone is not enough it says what information is missing. Always review before sending.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the message belongs to (tenant scope). |
id |
integer | No | Archive doc id (from a search result). Either id or message_id is required. |
message_id |
string | No | RFC Message-ID. Either id or message_id is required. |
Fetch all messages in a thread (by thread_id) within one archive, ordered chronologically. Metadata only — use get-message for a body.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the thread belongs to (tenant scope). |
thread_id |
string | ✓ Yes | Thread identifier (from a search/message result). |
Aggregate statistics for one archive: message count, total size, attachment count, indexed count, date range, and per-folder counts. oldest/newest are datetime strings; oldest_iso/newest_iso give the same instants in ISO-8601 UTC.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive to report on (tenant scope). |
LLM-ready feed for one context: rolling summary plus pinned and recent raw messages within the token cap. PREFERRED ROUTE for topic questions — one call instead of a search plus N get-message calls. Reach it via context-list (see what exists) or context-match (find the context for a query). Read summary_through_ts_iso to see what the summary actually covers: it is normally OLDER than summary_updated_at_iso, which is only when the summary was last recomputed. All timestamps are UTC; summary_through_ts_iso, summary_updated_at_iso and messages[].date_received_iso give the ISO-8601 form.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive the context belongs to (tenant scope). |
context_id |
integer | ✓ Yes | Context to feed. |
List all contexts of an archive with member counts and staleness. START HERE for topic questions: if a context already covers the subject, context-feed answers in one call. summary_updated_at_iso and created_at_iso give the ISO-8601 UTC form.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive (tenant scope). |
Fetch one context incl. rolling summary and resolved config (context → archive → platform cascade).
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive (tenant scope). |
context_id |
integer | ✓ Yes | Context id. |
Match a search query against existing contexts of an archive (lexical scoring). Use after context-list when the right context is not obvious by name, and before context-create for find-or-create flows. A hit means you can go straight to context-feed.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive (tenant scope). |
query |
string | ✓ Yes | Search query to match. |
List context members (pinned first, relevance-ordered). Each member is keyed by id (the archive doc id usable with get-message); date_sent_iso and created_at_iso give the ISO-8601 UTC form.
| Field | Type | Required | Description |
|---|---|---|---|
archive_id |
integer | ✓ Yes | Archive (tenant scope). |
context_id |
integer | ✓ Yes | Context id. |
limit |
integer | No | Default 50. |
offset |
integer | No | Default 0. |
include_excluded |
integer | No | 1 = include excluded members. |
MCP Tool Names
When using this integration through an AI assistant (Claude, ChatGPT, Cursor, etc.), the endpoints are available as MCP tools:
| Endpoint | MCP Tool Name |
|---|---|
| list-archives | email_archive_list_archives |
| search | email_archive_search |
| get-message | email_archive_get_message |
| list-attachments | email_archive_list_attachments |
| set-state | email_archive_set_state |
| draft-reply | email_archive_draft_reply |
| get-thread | email_archive_get_thread |
| get-stats | email_archive_get_stats |
| context-feed | email_archive_context_feed |
| context-list | email_archive_context_list |
| context-get | email_archive_context_get |
| context-match | email_archive_context_match |
| context-members | email_archive_context_members |
Website