> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentMail

> Keyword retriever over an AgentMail inbox.

`AgentMailRetriever` performs a keyword search over an [AgentMail](https://agentmail.to) 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 `Document`s. For semantic search, pair `AgentMailLoader` with your own vector store instead.

## Overview

| Class                | Package                                                                |
| :------------------- | :--------------------------------------------------------------------- |
| `AgentMailRetriever` | [`langchain-agentmail`](https://pypi.org/project/langchain-agentmail/) |

## Setup

Install the package:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
pip install -qU langchain-agentmail
```

Set your AgentMail API key (get one at [agentmail.to](https://agentmail.to)):

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
import getpass
import os

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

## Instantiation

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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

```python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
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 `Document`s and feed them into a real vector store. See the [document loader page](/oss/python/integrations/document_loaders/agentmail) for that flow.

## API reference

The package source lives at [github.com/agentmail-to/langchain-agentmail](https://github.com/agentmail-to/langchain-agentmail).

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/python/integrations/retrievers/agentmail.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>