Add AgentMail integration docs (provider, toolkit, loader, retriever) (#4055)

josephfeleke · web-flow · commit c7adb965defe · 2026-05-29T17:00:53.000+02:00
diff --git a/packages.yml b/packages.yml
@@ -792,3 +792,6 @@ packages:
   js: "@oracle/langchain-oracledb"
   downloads: 44000
   downloads_updated_at: "2026-05-18T00:23:32.797657+00:00"
+- name: langchain-agentmail
+  repo: agentmail-to/langchain-agentmail
+  js: "n/a"
diff --git a/src/oss/python/integrations/document_loaders/agentmail.mdx b/src/oss/python/integrations/document_loaders/agentmail.mdx
@@ -0,0 +1,85 @@
+---
+title: "AgentMail"
+description: "Load messages from an AgentMail inbox as LangChain Documents."
+---
+
+`AgentMailLoader` streams messages from an [AgentMail](https://agentmail.to) inbox as LangChain `Document`s—one document per message, plain-text body as `page_content`, sender / subject / labels / thread / attachment metadata on `metadata`. Useful for indexing an inbox into a vector store for RAG over email.
+
+## Overview
+
+| Class | Package |
+|:------|:--------|
+| `AgentMailLoader` | [`langchain-agentmail`](https://pypi.org/project/langchain-agentmail/) |
+
+## Setup
+
+Install the package:
+
+```bash
+pip install -qU langchain-agentmail
+```
+
+Set your AgentMail API key (get one at [agentmail.to](https://agentmail.to)):
+
+```python
+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
+from langchain_agentmail import AgentMailLoader
+
+loader = AgentMailLoader(
+    inbox_id="ib_abc123",
+    labels=["inbox"],  # optional — filter messages by label
+    limit=100,         # optional — cap the number of messages loaded
+)
+```
+
+## Load
+
+```python
+docs = loader.load()
+print(docs[0].page_content[:200])
+print(docs[0].metadata)
+```
+
+Each `Document` includes the following metadata keys (when present):
+
+- `inbox_id`, `message_id`, `thread_id`
+- `from`, `to`, `cc`, `subject`, `labels`, `timestamp`
+- `has_attachments`, `attachments`: a list of `{attachment_id, filename, content_type, size}`
+
+To download attachment bytes, pair the loader with `AgentMailGetAttachmentTool` from the toolkit—it returns a presigned download URL.
+
+## Lazy load
+
+For larger inboxes, stream documents one at a time instead of materializing the full list:
+
+```python
+for doc in loader.lazy_load():
+    print(doc.metadata["subject"])
+```
+
+## Indexing into a vector store
+
+```python
+from langchain_core.vectorstores import InMemoryVectorStore
+from langchain_openai import OpenAIEmbeddings
+
+docs = AgentMailLoader(inbox_id="ib_abc123", limit=200).load()
+
+store = InMemoryVectorStore.from_documents(docs, OpenAIEmbeddings())
+retriever = store.as_retriever(search_kwargs={"k": 5})
+
+retriever.invoke("Q3 invoice from acme")
+```
+
+## API reference
+
+The package source lives at [github.com/agentmail-to/langchain-agentmail](https://github.com/agentmail-to/langchain-agentmail).
diff --git a/src/oss/python/integrations/document_loaders/index.mdx b/src/oss/python/integrations/document_loaders/index.mdx
@@ -34,6 +34,14 @@ for document in loader.lazy_load():
 
 ## By category
 
+### Productivity tools
+
+The below document loaders allow you to load data from commonly used productivity tools.
+
+| Document Loader | API reference |
+|----------------|---------------|
+| [AgentMail](/oss/integrations/document_loaders/agentmail) | [`AgentMailLoader`](https://github.com/agentmail-to/langchain-agentmail) |
+
 ### Webpages
 
 The below document loaders allow you to load webpages.
@@ -82,6 +90,7 @@ The below document loaders allow you to load data from common data formats.
 ## All document loaders
 
 <Columns cols={3}>
+<Card title="AgentMail" icon="link" href="/oss/integrations/document_loaders/agentmail" arrow="true" cta="View guide" />
 <Card title="AgentQLLoader" icon="link" href="/oss/integrations/document_loaders/agentql" arrow="true" cta="View guide" />
 <Card title="AirbyteLoader" icon="link" href="/oss/integrations/document_loaders/airbyte" arrow="true" cta="View guide" />
 <Card title="Apify Dataset" icon="link" href="/oss/integrations/document_loaders/apify_dataset" arrow="true" cta="View guide" />
diff --git a/src/oss/python/integrations/providers/agentmail.mdx b/src/oss/python/integrations/providers/agentmail.mdx
@@ -0,0 +1,36 @@
+---
+title: "AgentMail integrations"
+description: "Integrate with AgentMail using LangChain Python."
+---
+
+[AgentMail](https://agentmail.to) is an inbox-as-an-API platform built for AI agents—provisioning, sending, replying, drafting, and inbound webhooks all available over a single HTTP API. The `langchain-agentmail` package wraps the AgentMail SDK as LangChain tools, plus a document loader and a retriever over an inbox.
+
+## Installation and setup
+
+<CodeGroup>
+```bash pip
+pip install langchain-agentmail
+```
+
+```bash uv
+uv add langchain-agentmail
+```
+</CodeGroup>
+
+Get your API key from [agentmail.to](https://agentmail.to) and set it as an environment variable:
+
+```bash
+export AGENTMAIL_API_KEY="your-api-key"
+```
+
+## Tools
+
+See the [AgentMail Toolkit](/oss/integrations/tools/agentmail) guide for details on the available tools, including sending and replying to messages, managing drafts, attachments, and labels.
+
+## Document loader
+
+See the [AgentMail Document Loader](/oss/integrations/document_loaders/agentmail) guide for loading messages from an inbox as LangChain `Document`s—useful for indexing into a vector store for RAG over email.
+
+## Retriever
+
+See the [AgentMail Retriever](/oss/integrations/retrievers/agentmail) guide for keyword search over an inbox.
diff --git a/src/oss/python/integrations/providers/all_providers.mdx b/src/oss/python/integrations/providers/all_providers.mdx
@@ -41,6 +41,14 @@ Browse the complete collection of integrations available for Python. LangChain P
         Open event-based protocol for connecting LangGraph agents to any frontend.
     </Card>
 
+    <Card
+        title="AgentMail"
+        href="/oss/integrations/providers/agentmail"
+        icon="link"
+    >
+        Inbox-as-an-API platform for AI agents — sending, replying, drafts, attachments, and inbound webhooks.
+    </Card>
+
     <Card
         title="AgentPhone"
         href="/oss/integrations/providers/agentphone"
diff --git a/src/oss/python/integrations/retrievers/agentmail.mdx b/src/oss/python/integrations/retrievers/agentmail.mdx
@@ -0,0 +1,61 @@
+---
+title: "AgentMail"
+description: "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
+pip install -qU langchain-agentmail
+```
+
+Set your AgentMail API key (get one at [agentmail.to](https://agentmail.to)):
+
+```python
+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
+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
+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/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).
diff --git a/src/oss/python/integrations/retrievers/index.mdx b/src/oss/python/integrations/retrievers/index.mdx
@@ -40,6 +40,7 @@ The below retrievers will search over an external index (e.g., constructed from
 ## All retrievers
 
 <Columns cols={3}>
+<Card title="AgentMail" icon="link" href="/oss/integrations/retrievers/agentmail" arrow="true" cta="View guide" />
 <Card title="Bedrock (Knowledge Bases)" icon="link" href="/oss/integrations/retrievers/bedrock" arrow="true" cta="View guide" />
 <Card title="Box" icon="link" href="/oss/integrations/retrievers/box" arrow="true" cta="View guide" />
 <Card title="Cognee" icon="link" href="/oss/integrations/retrievers/cognee" arrow="true" cta="View guide" />
diff --git a/src/oss/python/integrations/tools/agentmail.mdx b/src/oss/python/integrations/tools/agentmail.mdx
diff --git a/src/oss/python/integrations/tools/index.mdx b/src/oss/python/integrations/tools/index.mdx
