Email MCP Server

List emails

list_emails

Read-only

Browse emails in a mailbox with optional sender, subject, date, read, flag, reply, and attachment filters; get paginated results with metadata.

Instructions

List emails in a mailbox with optional filters. Returns paginated results with metadata (read/unread 🔵, flagged ⭐, replied ↩️, attachments 📎, labels 🏷️). List or machine-generated mail is marked 📰 newsletter / 🤖 automated from its RFC headers, with the unsubscribe URI when the sender offers one — personal mail carries no marker. Use get_email to fetch full body content. ProtonMail note: labels are represented as IMAP folders — use list_labels to discover them, then list_emails with mailbox="Labels/X" to find labeled emails.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`from`	No	Filter by sender address or name
`page`	No	Page number
`seen`	No	Filter: true=read only, false=unread only
`since`	No	Show emails after this date (ISO 8601)
`before`	No	Show emails before this date (ISO 8601)
`account`	Yes	Account name from list_accounts
`flagged`	No	Filter: true=flagged only, false=unflagged only
`mailbox`	No	Mailbox path (default: INBOX)	INBOX
`preview`	No	Include a ~200 character body preview per message. Off by default: it fetches extra bytes per message and lengthens the output.
`subject`	No	Filter by subject keyword
`answered`	No	Filter: true=replied, false=not yet replied
`pageSize`	No	Results per page
`has_attachment`	No	Filter: true=has attachments, false=no attachments

Output Schema

TableJSON Schema

Name	Required	Description	Default
`page`	Yes
`cache`	No
`count`	Yes
`total`	Yes
`emails`	Yes
`account`	Yes
`hasMore`	Yes
`mailbox`	Yes
`pageSize`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.6.0Oct 17, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / preview

Added value: +{
+  "default": false,
+  "description": "Include a ~200 character body preview per message. Off by default: it fetches extra bytes per message and lengthens the output.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "account": {
+      "type": "string"
+    },
+    "cache": {
+      "additionalProperties": false,
+      "properties": {
+        "offline": {
+          "const": true,
+          "type": "boolean"
+        },
+        "source": {
+          "const": "cache",
+          "type": "string"
+        },
+        "stale": {
+          "const": true,
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "type": "object"
+    },
+    "count": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "emails": {
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "answered": {
+            "type": "boolean"
+          },
+          "bulk": {
+            "additionalProperties": false,
+            "properties": {
+              "kind": {
+                "enum": [
+                  "newsletter",
+                  "automated"
+                ],
+                "type": "string"
+              },
+              "listId": {
+                "type": "string"
+              },
+              "oneClick": {
+                "type": "boolean"
+              },
+              "unsubscribe": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "oneClick"
+            ],
+            "type": "object"
+          },
+          "date": {
+            "type": "string"
+          },
+          "flagged": {
+            "type": "boolean"
+          },
+          "from": {
+            "additionalProperties": false,
+            "properties": {
+              "address": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "address"
+            ],
+            "type": "object"
+          },
+          "hasAttachments": {
+            "type": "boolean"
+          },
+          "id": {
+            "type": "string"
+          },
+          "labels": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "preview": {
+            "type": "string"
+          },
+          "seen": {
+            "type": "boolean"
+          },
+          "subject": {
+            "type": "string"
+          },
+          "to": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "address": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "address"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "required": [
+          "id",
+          "subject",
+          "from",
+          "to",
+          "date",
+          "seen",
+          "flagged",
+          "answered",
+          "hasAttachments",
+          "labels"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "hasMore": {
+      "type": "boolean"
+    },
+    "mailbox": {
+      "type": "string"
+    },
+    "page": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "pageSize": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "total": {
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "account",
+    "mailbox",
+    "total",
+    "page",
+    "pageSize",
+    "hasMore",
+    "count",
+    "emails"
+  ],
+  "type": "object"
+}

First observedv0.2.3Jul 30, 2026

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description goes well beyond: it documents pagination, the emoji marker legend for message state, and the newsletter/automated classification derived from RFC headers including the unsubscribe URI. This is behavior an agent could not infer from annotations or schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose, then the output markers, then the alternatives and the ProtonMail caveat — a sensible ordering with no filler sentences. The dense emoji legend is information-carrying but slightly heavy for a description that must also stay scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 13 parameters, all schema-documented, plus an output schema, the description does the right thing by not re-explaining returns. It covers pagination, filtering, sibling routing, and the ProtonMail label quirk. The only residual is that the relationship to get_emails/search_emails is left unstated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description earns above baseline by adding a non-obvious convention the schema lacks: ProtonMail labels are IMAP folders reached via mailbox="Labels/X", which meaningfully extends how the mailbox parameter should be used.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List emails in a mailbox') plus its scope ('with optional filters'), and explicitly routes full-body retrieval to get_email. It does not, however, differentiate itself from the confusingly similar siblings get_emails and search_emails, which an agent must disambiguate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete usage instructions: call get_email for full bodies, and for ProtonMail run list_labels first then list_emails with mailbox="Labels/X". That is real when/how guidance. It stops short of saying when to prefer this over search_emails or get_emails, so no explicit exclusion is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server