imap_list_mailboxes

Description

Returns up to 200 visible mailboxes/folders for the specified account. Includes hierarchy delimiter information when supported by the server.

Mailbox names are server-dependent and may include special characters or Unicode. Common mailboxes include INBOX, Sent, Drafts, Archive, and Trash.

Input Parameters

body.account_id

string

default:"default"

Account identifier matching an environment variable configuration.Pattern: ^[A-Za-z0-9_-]{1,64}$

Response

summary

string

required

Human-readable summary of the operation outcome.Example: "5 mailbox(es)"

data

object

required

Show properties

status

string

required

Overall operation status: "ok", "partial", or "failed".

issues

object[]

required

Array of diagnostic issues encountered during the operation.

Show issue object

code

string

required

Error code: "invalid_input", "auth_failed", "not_found", "timeout", "conflict", or "internal".

stage

string

required

Operation stage where issue occurred (e.g., "connect_authenticated", "list_mailboxes").

message

string

required

Actionable error message.

retryable

boolean

required

Whether the operation can be retried.

next_action

object

required

Suggested follow-up action.

Show properties

instruction

string

required

Human-readable instruction for next step.

tool

string

required

Recommended tool to call next (typically "imap_search_messages").

arguments

object

required

Suggested arguments for the next tool call.

account_id

string

required

Account identifier used for the request.

mailboxes

object[]

required

Array of mailboxes (max 200).

Show mailbox object

name

string

required

Mailbox name. May contain hierarchy separators (e.g., "Archive/2024").

delimiter

string

Hierarchy delimiter character if supported by server (e.g., "/", ".", or null).

Examples

{
  "method": "tools/call",
  "params": {
    "name": "imap_list_mailboxes",
    "arguments": {
      "account_id": "default"
    }
  }
}

Error Cases

Invalid Account ID

{
  "error": {
    "code": "invalid_input",
    "message": "account_id must match pattern ^[A-Za-z0-9_-]{1,64}$",
    "details": {}
  },
  "meta": {
    "now_utc": "2024-03-15T10:30:45.123Z",
    "duration_ms": 1
  }
}

Account Not Found

{
  "error": {
    "code": "not_found",
    "message": "Account 'unknown' not found in configuration",
    "details": {}
  },
  "meta": {
    "now_utc": "2024-03-15T10:30:45.123Z",
    "duration_ms": 2
  }
}

Mailbox Limits

The response is limited to 200 mailboxes. If your account has more mailboxes, only the first 200 will be returned. This limit is enforced to keep response sizes manageable.

Special Mailbox Names

Mailbox names are case-sensitive and server-dependent. Common variations include:

INBOX (always uppercase per RFC 3501)
Sent vs Sent Items vs Sent Mail
Trash vs Deleted Items vs Deleted Messages
Drafts vs Draft
Archive vs All Mail

Always use the exact name returned by this tool when referencing mailboxes in other operations.

imap_list_accounts - List all configured accounts
imap_verify_account - Verify account connectivity before listing mailboxes
imap_search_messages - Search messages in a specific mailbox

Overview

Account & Mailbox Tools

Read Operations

Write Operations

Description

Input Parameters

Response

Examples

Error Cases

Invalid Account ID

Account Not Found

Mailbox Limits

Special Mailbox Names

Build docs developers (and LLMs) love

Overview

Account & Mailbox Tools

Read Operations

Write Operations

​Description

​Input Parameters

​Response

​Examples

​Error Cases

​Invalid Account ID

​Account Not Found

​Mailbox Limits

​Special Mailbox Names

​Related Tools

Build docs developers (and LLMs) love

Description

Input Parameters

Response

Examples

Error Cases

Invalid Account ID

Account Not Found

Mailbox Limits

Special Mailbox Names

Related Tools