Email Archive

Create a new autonomous email archive owned by an email address.

List archives with their source counts. Optionally filter by owner email.

Deactivate an archive. Stops syncing into it; archived messages are preserved.

Register an external mail source (Gmail, Outlook, custom IMAP) for archiving. Credentials are stored encrypted. Link it to an archive separately with link-source.

List all archive sources (mailboxes), or the sources linked to a specific archive. Never returns credentials.

Link a mailbox source to an archive so its mail flows into that archive. A source can feed multiple archives.

Unlink a source from an archive. Stops future syncing into it; already-archived messages are preserved.

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.

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.

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.

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.

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.

Fetch all messages in a thread (by thread_id) within one archive, ordered chronologically. Metadata only — use get-message for a body.

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.

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.

Fold the oldest non-pinned messages of a context into its rolling summary. Normally triggered automatically when the context exceeds its compression threshold.

Create a context in an archive (find-or-create on name). Seeds members by keyword match. Pass keywords as an array or CSV string (required, handler-validated). Optional: filters object.

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.

Fetch one context incl. rolling summary and resolved config (context → archive → platform cascade).

Update context fields (name, query, parent_id, token_cap, compress_threshold, auto_pull, embed_strategy). keywords (array/CSV) triggers a re-seed; filters object replaces filters. Handler-validated.

Delete a context (members removed, messages preserved). Fails 409 if it has sub-contexts.

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.

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.

Manage one membership: add, remove, pin, unpin, exclude (stay out despite matches), include.