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.

Changed1 schema field changedOct 13, 2026

addedOutput schema / properties / inboxes / items / properties / access

Added value: +{
+  "description": "Present only when this inbox is connected for one direction. send_only: no IMAP, so it cannot read, search, organize or draft. receive_only: no SMTP, so it cannot send, reply, forward or schedule. Absent means the inbox does both.",
+  "enum": [
+    "send_only",
+    "receive_only"
+  ],
+  "type": "string"
+}

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.4/5.0

Behavior4/5

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds context the annotations cannot carry: results are limited to what the API key may access, and it explains the surprising connector-vs-brand behavior (app-password Gmail reports provider 'imap').

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?

Three sentences, front-loaded with purpose and the call-order rule, with the disambiguation example placed last where it belongs. Dense and mostly non-redundant, though the provider/service distinction is stated twice (in prose and in the schema), which slightly dilutes it.

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?

An output schema exists, so return values need no prose, yet the description still enumerates the returned fields (UUID, address, display name, provider, service, capabilities) which lets an agent decide whether it needs include_capabilities. Nothing required for correct invocation is missing.

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 reinforcing the provider/service distinction with a concrete worked example ("A Gmail account connected with an app password has provider 'imap' and service 'gmail'") that prevents the most likely misuse of these two enum parameters.

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?

States a specific verb and resource ("List every inbox (mailbox or account)") plus the authorization scope ("this API key may use"). It clearly separates itself from all siblings by declaring the discovery role: it yields the inbox_id the other tools consume.

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?

"Call it FIRST for the inbox_id the other tools take" gives explicit ordering guidance relative to the rest of the toolset, and the closing sentence tells the agent which filter to reach for (service over provider). There is no explicit when-not or named alternative, but no competing inbox-listing tool exists among the siblings.

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.