MCP Emails

List Inboxes

inbox_list

Read-onlyIdempotent

List every inbox (mailbox or account) this API key may use. Call it FIRST for the inbox_id the other tools take. Each entry carries the UUID, email address, display name, provider (the connector: gmail/outlook/fastmail/imap), optional service brand (the account behind an IMAP connection: gmail/fastmail/icloud/yahoo/zoho/yandex/generic) and a capabilities object. A Gmail account connected with an app password has provider 'imap' and service 'gmail', so filter on service, not provider, to find a mailbox by brand.

Input Schema

TableJSON Schema

Name	Required	Description
`inbox`	No	Return only this inbox: its email address or inbox_id.
`service`	No	Return only inboxes whose account BRAND is this. Set on inboxes reached over plain IMAP; null for a first-party connector, so service 'gmail' means Gmail-over-app-password and provider 'gmail' means Gmail-over-Google-API. Omit for all of them.
`provider`	No	Return only inboxes reached through this CONNECTOR. Not the brand of the address: a Gmail mailbox connected over IMAP is provider 'imap'. Use `service` for the brand. Omit for all of them.
`include_capabilities`	No	Include each inbox's capabilities object. Set false for a compact list of inbox_id, email address, display name, provider and brand.

Output Schema

TableJSON Schema

Name	Required	Description
`notes`	No	Server notes about how this call was handled — for example an argument that was not applied because the selected action does not accept it. Written by MCP Emails, not taken from any message, and absent when there is nothing to report.
`filter`	No	The provider/service/inbox filter that was applied.
`inboxes`	Yes
`matched`	No	Present only on a filtered call that matched nothing. Always 0; its presence is what distinguishes an unmatched filter from an empty account, which carries setup_required instead.
`message`	No	What happened, when `inboxes` is empty: either that no mailbox is connected yet, or that the filter matched none of the ones that are.
`available`	No	Every inbox this key can reach, on a filtered call that matched none of them, so the filter can be corrected without a second call.
`setup_url`	No	Where the user connects their first mailbox.
`setup_required`	No	Present and true ONLY when this key can reach no mailbox at all. Never set by a filter that matched nothing — see `matched`.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedSep 23, 2026

addedInput schema / properties / inbox

Added value: +{
+  "description": "Return only this inbox: its email address or inbox_id.",
+  "type": "string"
+}

changedOutput schema / properties / filter / description

Previous value: -"The provider/service filter that was applied."New value: +"The provider/service/inbox filter that was applied."

addedOutput schema / properties / filter / properties / inbox
```
Added value: +{
+  "type": "string"
+}
```

Changed8 schema fields changedSep 21, 2026

changedInput schema / properties / provider / description

Previous value: -"Return only inboxes served by this provider. Omit for all of them."New value: +"Return only inboxes reached through this CONNECTOR. Not the brand of the address: a Gmail mailbox connected over IMAP is provider 'imap'. Use `service` for the brand. Omit for all of them."

addedInput schema / properties / service

Added value: +{
+  "description": "Return only inboxes whose account BRAND is this. Set on inboxes reached over plain IMAP; null for a first-party connector, so service 'gmail' means Gmail-over-app-password and provider 'gmail' means Gmail-over-Google-API. Omit for all of them.",
+  "enum": [
+    "gmail",
+    "fastmail",
+    "icloud",
+    "yahoo",
+    "zoho",
+    "yandex",
+    "generic"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / available

Added value: +{
+  "description": "Every inbox this key can reach, on a filtered call that matched none of them, so the filter can be corrected without a second call.",
+  "items": {
+    "additionalProperties": true,
+    "properties": {
+      "email_address": {
+        "type": "string"
+      },
+      "provider": {
+        "type": "string"
+      },
+      "service": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "email_address",
+      "provider"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / filter

Added value: +{
+  "additionalProperties": false,
+  "description": "The provider/service filter that was applied.",
+  "properties": {
+    "provider": {
+      "type": "string"
+    },
+    "service": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

addedOutput schema / properties / matched

Added value: +{
+  "description": "Present only on a filtered call that matched nothing. Always 0; its presence is what distinguishes an unmatched filter from an empty account, which carries setup_required instead.",
+  "type": "integer"
+}

addedOutput schema / properties / message

Added value: +{
+  "description": "What happened, when `inboxes` is empty: either that no mailbox is connected yet, or that the filter matched none of the ones that are.",
+  "type": "string"
+}

addedOutput schema / properties / setup_required

Added value: +{
+  "description": "Present and true ONLY when this key can reach no mailbox at all. Never set by a filter that matched nothing — see `matched`.",
+  "type": "boolean"
+}

addedOutput schema / properties / setup_url

Added value: +{
+  "description": "Where the user connects their first mailbox.",
+  "type": "string"
+}

Changed6 schema fields changedSep 10, 2026

changedInput schema / properties / include_capabilities / description

Previous value: -"Whether each inbox includes its capabilities object (which inbox features — flags, folders, labels, move, copy, delete, forward, drafts, contacts_api, scheduling — are supported). Defaults to true; set false for a compact inbox list of just inbox_id, email address, display name, provider and service brand."New value: +"Include each inbox's capabilities object. Set false for a compact list of inbox_id, email address, display name, provider and brand."

changedInput schema / properties / provider / description

Previous value: -"Optional filter — return only inboxes (email accounts/mailboxes) served by this provider. One of: gmail, outlook, fastmail, imap. Omit to list every inbox the API key can access."New value: +"Return only inboxes served by this provider. Omit for all of them."

addedOutput schema / properties / inboxes / items / properties / compatibility
```
Added value: +{
+  "additionalProperties": true,
+  "type": "object"
+}
```

addedOutput schema / properties / inboxes / items / properties / sender_identities

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "display_name": {
+        "type": "string"
+      },
+      "email_address": {
+        "type": "string"
+      },
+      "is_default": {
+        "type": "boolean"
+      },
+      "is_primary": {
+        "type": "boolean"
+      },
+      "reply_to": {
+        "type": [
+          "string",
+          "null"
+        ]
+      }
+    },
+    "required": [
+      "email_address",
+      "display_name",
+      "is_primary",
+      "is_default"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / inboxes / items / properties / sender_identity_status

Added value: +{
+  "enum": [
+    "available",
+    "reconnect_required",
+    "unavailable"
+  ],
+  "type": "string"
+}

addedOutput schema / properties / notes

Added value: +{
+  "description": "Server notes about how this call was handled — for example an argument that was not applied because the selected action does not accept it. Written by MCP Emails, not taken from any message, and absent when there is nothing to report.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

First observedJun 24, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare the operation read-only, idempotent and non-destructive, and the description adds value by explaining exactly what each entry contains and by clarifying the subtle provider-vs-service behavior with a Gmail-over-IMAP example. It does not contradict any annotation.

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

Conciseness5/5

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

The description is about three sentences of dense, front-loaded information. It starts with the core purpose, then the most important sequencing instruction, then the payload summary, then the critical filtering caveat. No sentence is wasted.

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

Completeness5/5

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

For a read-only list tool with an output schema, annotations and fully described parameters, the description covers everything an agent needs to call it correctly: what it returns, why to call it first, how to interpret provider vs service, and how to filter. The output schema handles return-value details, and the annotations handle safety expectations.

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 description coverage is 100%, so the schema already documents every parameter. The description adds meaningful semantic context beyond the schema, especially the crucial warning that a Gmail account connected with an app password has provider 'imap' and service 'gmail'. This helps the agent choose between `provider` and `service` correctly.

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

Purpose5/5

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

The description opens with a specific verb-object pair, 'List every inbox (mailbox or account)', and ties it to the API key's accessible scope. It goes beyond the title by explaining the useful payload fields and the provider/service distinction. It is immediately distinguishable from sibling list tools by resource type and by the explicit 'Call it FIRST' framing.

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?

The description gives explicit usage context: 'Call it FIRST for the inbox_id the other tools take', which tells an agent when to invoke this tool relative to its siblings. It also gives concrete filtering guidance, such as filtering on service rather than provider to find a mailbox by brand. It stops short of stating specific when-not-to-use conditions, but the sequencing instruction is strong.

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

All MCP Emails tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.