From 15a6ed8d6e57b9bf7a8c4f99e502f706edfdfe17 Mon Sep 17 00:00:00 2001
From: "fern-api[bot]" <115122769+fern-api[bot]@users.noreply.github.com>
Date: Tue, 3 Mar 2026 00:39:35 +0000
Subject: [PATCH] Add Lists documentation page to Core Concepts

---
 fern/docs.yml                      |  3 +
 fern/pages/core-concepts/lists.mdx | 88 ++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100644 fern/pages/core-concepts/lists.mdx

diff --git a/fern/docs.yml b/fern/docs.yml
index 089e126..a04944d 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -228,6 +228,9 @@ navigation:
           - page: Labels
             icon: fa-solid fa-tags
             path: pages/core-concepts/labels.mdx
+          - page: Lists
+            icon: fa-solid fa-filter
+            path: pages/core-concepts/lists.mdx
           - page: Attachments
             icon: fa-solid fa-paperclip
             path: pages/core-concepts/attachments.mdx
diff --git a/fern/pages/core-concepts/lists.mdx b/fern/pages/core-concepts/lists.mdx
new file mode 100644
index 0000000..007b8b0
--- /dev/null
+++ b/fern/pages/core-concepts/lists.mdx
@@ -0,0 +1,88 @@
+---
+title: Lists
+subtitle: Filter emails by allowing or blocking specific addresses and domains.
+slug: lists
+description: Learn how to use Lists to control which email addresses and domains your agents can send to or receive from.
+---
+
+## What are Lists?
+
+`Lists` allow you to filter emails by allowing or blocking specific email addresses or domains. There are four list types based on two dimensions:
+
+- **Direction**: `send` or `receive`
+- **Type**: `allow` or `block`
+
+| List | Description |
+| --- | --- |
+| Receive allow | Only accept emails from these addresses or domains |
+| Receive block | Reject emails from these addresses or domains |
+| Send allow | Only send emails to these addresses or domains |
+| Send block | Prevent sending emails to these addresses or domains |
+
+Each entry can be either a full email address (e.g., `partner@example.com`) or an entire domain (e.g., `example.com`).
+
+## SDK examples
+
+### List entries
+
+Retrieve entries from a list with optional pagination.
+
+<CodeBlocks>
+```python title="Python"
+entries = client.lists.list("receive", "allow", limit=10)
+```
+
+```typescript title="TypeScript"
+const entries = await client.lists.list("receive", "allow", { limit: 10 });
+```
+</CodeBlocks>
+
+### Create entry
+
+Add an email address or domain to a list. The `reason` parameter is optional and available on block lists.
+
+<CodeBlocks>
+```python title="Python"
+# allow list - no reason needed
+client.lists.create("receive", "allow", entry="partner@example.com")
+
+# block list - reason optional
+client.lists.create("receive", "block", entry="spam@example.com", reason="spam")
+```
+
+```typescript title="TypeScript"
+// allow list - no reason needed
+await client.lists.create("receive", "allow", { entry: "partner@example.com" });
+
+// block list - reason optional
+await client.lists.create("receive", "block", { entry: "spam@example.com", reason: "spam" });
+```
+</CodeBlocks>
+
+### Get entry
+
+Retrieve a specific entry from a list by its email address or domain.
+
+<CodeBlocks>
+```python title="Python"
+entry = client.lists.get("receive", "allow", entry="partner@example.com")
+```
+
+```typescript title="TypeScript"
+const entry = await client.lists.get("receive", "allow", "partner@example.com");
+```
+</CodeBlocks>
+
+### Delete entry
+
+Remove an entry from a list.
+
+<CodeBlocks>
+```python title="Python"
+client.lists.delete("receive", "allow", entry="partner@example.com")
+```
+
+```typescript title="TypeScript"
+await client.lists.delete("receive", "allow", "partner@example.com");
+```
+</CodeBlocks>