Skip to main content
The Mail IMAP MCP Server exposes 10 tools organized into three categories: account management, message operations, and write operations.

​
Tool Categories

​
Account Management

Tools for discovering and verifying IMAP accounts.

imap_list_accounts

List configured accounts without exposing secrets

imap_verify_account

Verify account connectivity, auth, and capabilities

imap_list_mailboxes

List visible mailboxes/folders

​
Message Operations

Tools for searching, reading, and retrieving messages.

imap_search_messages

Search mailbox with filters and pagination

imap_get_message

Get parsed message details with optional enrichments

imap_get_message_raw

Get bounded RFC822 source for diagnostics

​
Write Operations

Tools for modifying messages and mailboxes. All write operations require MAIL_IMAP_WRITE_ENABLED=true.

imap_update_message_flags

Add/remove IMAP flags on a message

imap_copy_message

Copy message to mailbox in same or different account

imap_move_message

Move message to mailbox in same account

imap_delete_message

Delete message from mailbox

​
Shared Input Types

All tools accept these common input parameters with consistent validation rules.

​
account_id

  • Type: string
  • Pattern: ^[A-Za-z0-9_-]{1,64}$
  • Default: "default"
Identifies which configured IMAP account to use. Maps to environment variables prefixed with MAIL_IMAP_<ACCOUNT>_.

​
mailbox

  • Type: string
  • Length: 1..256 characters
IMAP mailbox/folder name (e.g., "INBOX", "Sent", "Archive/2024").

​
message_id

  • Type: string
  • Format: imap:{account_id}:{mailbox}:{uidvalidity}:{uid}
Stable message identifier that survives folder moves within the same account. Validation rules:
  • Prefix must be imap
  • uidvalidity and uid must be non-negative integers
  • Parsed account_id must match requested account
Example: imap:default:INBOX:1234567890:42

​
limit

  • Type: integer
  • Range: 1..50
  • Default: 10
Maximum number of results to return in paginated responses.

​
Shared Output Envelope

All tools return a consistent envelope structure with three sections:

​
Success Response

{
  "summary": "human-readable one-line outcome",
  "data": {
    // Tool-specific response data
  },
  "meta": {
    "now_utc": "2024-03-15T10:30:00Z",
    "duration_ms": 125
  }
}

​
Error Response

{
  "error": {
    "code": "invalid_input",
    "message": "actionable error message",
    "details": {
      // Optional context-specific details
    }
  },
  "meta": {
    "now_utc": "2024-03-15T10:30:00Z",
    "duration_ms": 50
  }
}

​
Partial Success Response

Runtime IMAP command failures are returned in successful data payloads to preserve partial results: 
{
  "summary": "Completed with issues",
  "data": {
    "status": "partial",
    "issues": [
      {
        "code": "fetch_failed",
        "stage": "envelope_fetch",
        "message": "Failed to fetch envelope for UID 123",
        "retryable": true,
        "uid": 123
      }
    ],
    "next_action": {
      "instruction": "Retry failed UIDs individually",
      "tool": "imap_get_message",
      "arguments": { "message_id": "imap:default:INBOX:1234567890:123" }
    }
    // ... partial data
  },
  "meta": {
    "now_utc": "2024-03-15T10:30:00Z",
    "duration_ms": 200
  }
}
Status values:
  • ok - operation completed successfully
  • partial - operation completed with some failures
  • failed - operation failed completely

​
Error Codes

The server returns consistent error codes in the error.code field:
CodeDescriptionWhen Used
invalid_inputInput validation failedMalformed parameters, conflicting options, out-of-range values
auth_failedAuthentication failedInvalid credentials, expired password, account locked
not_foundResource not foundNon-existent message_id, mailbox, or account
timeoutOperation timed outIMAP server unresponsive, network issues
conflictState conflict detectedCursor expired, UIDVALIDITY changed, mailbox deleted
internalInternal server errorUnexpected failures, parser errors, resource exhaustion

​
Common Validation Errors

{
  "error": {
    "code": "invalid_input",
    "message": "Cannot combine cursor with search criteria",
    "details": {
      "provided": ["cursor", "query"]
    }
  }
}

{
  "error": {
    "code": "invalid_input",
    "message": "Invalid message_id format",
    "details": {
      "message_id": "invalid-format",
      "expected": "imap:{account}:{mailbox}:{uidvalidity}:{uid}"
    }
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Search cursor expired or invalid",
    "details": {
      "cursor": "abc123...",
      "action": "retry search without cursor"
    }
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Message not found (may have been deleted or moved)",
    "details": {
      "message_id": "imap:default:INBOX:1234567890:42"
    }
  }
}

​
Write Gate

Write operations (imap_update_message_flags, imap_copy_message, imap_move_message, imap_delete_message) are disabled by default and must be explicitly enabled: 
export MAIL_IMAP_WRITE_ENABLED=true
Attempting write operations without this flag returns: 
{
  "error": {
    "code": "invalid_input",
    "message": "Write operations disabled. Set MAIL_IMAP_WRITE_ENABLED=true to enable.",
    "details": {
      "tool": "imap_update_message_flags"
    }
  }
}

​
Next Steps

Account Management

Start with account discovery and verification

Search Messages

Learn about search filters and pagination

Configuration

Configure accounts via environment variables

Quick Start

Get started with your first IMAP account

Build docs developers (and LLMs) love

Get started for freeTalk to us