MCPEmails

List Inboxes

inbox_list

Read-onlyIdempotent

List every inbox (mailbox or account) this API key may use. It returns 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 service, not provider, is a mailbox's brand.

Input 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

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 MCPEmails, 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 changedNov 2, 2026

changedOutput schema / properties / inboxes / items / properties / status / description

Previous value: -"Absent when the inbox is usable. \"reconnect_required\" or \"unavailable\": do not offer it as a choice; tell the user (see hint and reconnect_url). \"parked\": outside the plan's inbox cap."New value: +"Absent when the inbox is usable. \"reconnect_required\" or \"unavailable\": not a usable choice; hint says why, reconnect_url is the user's fix. \"parked\": connected but inactive; see hint."

Changed3 schema fields changedOct 26, 2026

addedOutput schema / properties / inboxes / items / properties / hint
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / inboxes / items / properties / reconnect_url
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / inboxes / items / properties / status

Added value: +{
+  "description": "Absent when the inbox is usable. \"reconnect_required\" or \"unavailable\": do not offer it as a choice; tell the user (see hint and reconnect_url). \"parked\": outside the plan's inbox cap.",
+  "type": "string"
+}

Changed1 schema field changedOct 20, 2026

changedOutput schema / properties / notes / description

Previous value: -"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."New value: +"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 MCPEmails, not taken from any message, and absent when there is nothing to report."

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

Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral context: scope is limited to the API key's permitted inboxes, and it explains the provider-vs-service ambiguity that would otherwise cause misreads of the result. It does not mention ordering or pagination, so not a 5.

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 purpose and the inbox_id payoff, then explains the data model. The closing Gmail app-password example restates the preceding sentence's provider/service point rather than adding new information, which is mild redundancy.

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?

Output schema exists, so return values need little explanation, yet the description still characterizes the fields an agent will inspect. Given four optional filters and a simple read, the definition is complete enough to invoke correctly; only the absence of list-ordering/volume expectations leaves a small gap.

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

Parameters3/5

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

Schema coverage is 100% and the schema already spells out the provider/service distinction and the include_capabilities behavior. The description reinforces the trickiest semantic point (service is the brand, provider is the connector) but adds little beyond what the schema documents, so the baseline 3 applies.

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 auth scope ('this API key may use') and the key output ('the inbox_id the other tools take'). Clear enough to distinguish from folder_list or draft_list as an account-discovery tool.

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 sentence 'It returns the inbox_id the other tools take' implicitly routes the agent here before calling inbox-scoped tools, and the filter parameters carry 'Omit for all of them' guidance. No explicit when-not or named alternative is given, but the usage context is clear for a discovery tool.

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

All MCPEmails 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.