Skip to main content
AgentMailRetriever performs a keyword search over an AgentMail inbox. It loads recent messages via AgentMailLoader, scores them in-process with a case-insensitive substring match (subject hits weighted 2×), and returns the top-k as LangChain Documents. For semantic search, pair AgentMailLoader with your own vector store instead.

​
Overview

ClassPackage
AgentMailRetrieverlangchain-agentmail

​
Setup

Install the package: 
pip install -qU langchain-agentmail
Set your AgentMail API key (get one at agentmail.to): 
import getpass
import os

if not os.environ.get("AGENTMAIL_API_KEY"):
    os.environ["AGENTMAIL_API_KEY"] = getpass.getpass("AgentMail API key:\n")

​
Instantiation

from langchain_agentmail import AgentMailRetriever

retriever = AgentMailRetriever(
    inbox_id="ib_abc123",
    k=5,              # number of documents to return
    labels=["inbox"], # optional — filter messages by label
    scan_limit=50,    # number of messages to scan before ranking
)

​
Usage

docs = retriever.invoke("invoice from acme")
for doc in docs:
    print(doc.metadata["subject"], "—", doc.metadata.get("from"))
The retriever returns the same Document shape as AgentMailLoader — full plain-text body in page_content, plus inbox/message/thread/sender metadata.

​
When to use the loader instead

AgentMailRetriever is the “just give me recent messages matching X” escape hatch — no embeddings, no vector store. If you need semantic retrieval, ranking by relevance, or filtering across millions of messages, use AgentMailLoader to materialize Documents and feed them into a real vector store. See the document loader page for that flow.

​
API reference

The package source lives at github.com/agentmail-to/langchain-agentmail.
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.
Edit this page on GitHub or file an issue.