# Advanced Configuration This document covers advanced configuration options beyond the basic account setup. ## Cursor Pagination Configuration ### Cursor TTL Cursors expire after a configurable time-to-live. Shorter values improve memory usage but require more frequent re-searches. ```bash # Default: 600 seconds (10 minutes) MAIL_IMAP_CURSOR_TTL_SECONDS=600 ``` **Trade-offs:** - Shorter TTL: Less memory usage, more frequent re-searches needed - Longer TTL: Better user experience for slow workflows, higher memory usage ### Cursor Storage Limit Maximum number of cursors stored in memory. When exceeded, oldest unused cursors are evicted (LRU). ```bash # Default: 512 entries MAIL_IMAP_CURSOR_MAX_ENTRIES=512 ``` **Trade-offs:** - Lower limit: Less memory usage, cursors may expire sooner - Higher limit: Supports more concurrent searches, higher memory usage ## Write Operation Retention ### Completed Operation Storage Limit Maximum number of completed write operations retained in memory for `imap_get_operation`. ```bash # Default: 256 entries MAIL_IMAP_OPERATION_MAX_ENTRIES=256 ``` Behavior: - Pending and running operations are never evicted by this limit. - When the limit is exceeded, the oldest completed operations are evicted first. - After eviction, polling or canceling that operation returns `not_found`. ## Read Session Cache ### Read Session Cache TTL Idle authenticated IMAP read sessions are cached per account for reuse by read tools. ```bash # Default: 120 seconds MAIL_IMAP_READ_SESSION_CACHE_TTL_SECONDS=120 ``` **Trade-offs:** - Shorter TTL: Less idle server state, more reconnects - Longer TTL: Better reuse for bursty MCP clients, more idle authenticated sessions ### Read Session Cache Size Maximum number of idle read sessions retained per account. ```bash # Default: 4 idle sessions per account MAIL_IMAP_READ_SESSION_CACHE_MAX_PER_ACCOUNT=4 ``` Behavior: - `0` disables the read-session cache - In-flight read requests may still open more connections than this limit - Excess returned sessions are logged out instead of retained ## Message Processing Limits These server-wide limits bound work performed by `imap_get_message`: ```bash # Default: 8388608 bytes (8 MiB) fetched while assembling one message MAIL_IMAP_MESSAGE_FETCH_BUDGET_BYTES=8388608 # Default: 16777216 bytes (16 MiB) decoded across one message MAIL_IMAP_MESSAGE_DECODE_BUDGET_BYTES=16777216 # Default: 32 nested MIME levels MAIL_IMAP_MIME_MAX_DEPTH=32 # Default: 250 MIME parts MAIL_IMAP_MIME_MAX_PARTS=250 # Default: 10485760 bytes (10 MiB) of complete decoded attachment payloads processed for text extraction MAIL_IMAP_ATTACHMENT_EXTRACT_BUDGET_BYTES=10485760 ``` Behavior: - A conforming IMAP server is asked for at most the raw-message fetch budget. When a message is larger, `imap_get_message` parses only that bounded prefix and returns `partial` status with a fetch-budget issue. - The decode budget bounds decoded MIME payload bytes. Content beyond the limit is omitted or truncated, and the result reports the limit. - MIME nesting deeper than the depth limit or a part count beyond the configured maximum returns header-only metadata with a diagnostic issue instead of recursively parsing the overflowing structure. - The attachment extraction budget applies only to complete messages. Incomplete messages never extract attachment text; attachments that do not fit the extraction budget remain metadata-only and produce an issue rather than a partial extraction. - Attachment `size_bytes` is the complete decoded payload size when known. It is `null` or absent when the complete decoded size is unavailable or incomplete, and unknown size is never represented as zero. ## Timeout Configuration All timeouts are in milliseconds. Adjust based on network conditions and server performance. ### Connection Timeout Time to establish TCP connection and TLS handshake. ```bash # Default: 30000 ms (30 seconds) MAIL_IMAP_CONNECT_TIMEOUT_MS=30000 ``` **When to increase:** - High-latency networks - Slow TLS handshake on constrained systems - Network congestion issues ### Greeting Timeout Time to receive IMAP server greeting after connection. ```bash # Default: 15000 ms (15 seconds) MAIL_IMAP_GREETING_TIMEOUT_MS=15000 ``` **When to increase:** - Overloaded IMAP servers - Slow authentication backends - Geographically distant servers ### Socket Timeout Time for individual socket operations (idle, read, write). This is the timeout for most IMAP commands. ```bash # Default: 300000 ms (5 minutes) MAIL_IMAP_SOCKET_TIMEOUT_MS=300000 ``` **When to increase:** - Processing large mailboxes - Slow message retrieval - Complex search operations **When to decrease:** - Require faster failure detection - Implement custom retry logic ## TLS Trust Configuration ### Custom CA Bundle Use a PEM bundle when the IMAP server certificate chains to a private CA or a self-signed test CA that is not in the default WebPKI roots. ```bash # Default: unset MAIL_IMAP_CA_CERT_PATH=/path/to/ca-certificates.pem ``` Rules: - The file must contain one or more PEM-encoded certificates. - Default WebPKI roots remain enabled; this file adds trust anchors, it does not replace them. - Hostname verification still applies. Use cases: - Internal mail servers with private PKI - Test fixtures such as GreenMail with self-signed certificates - Enterprise TLS interception environments where a private root CA is required ## Write Operations Configuration ### Enabling Write Operations ```bash # Default: false MAIL_IMAP_WRITE_ENABLED=true ``` **Enables:** - `imap_apply_to_messages` - Bulk message mutation - `imap_update_message_flags` - Bulk message flag updates - `imap_manage_mailbox` - Mailbox lifecycle operations **Security consideration:** Only enable if you need these operations. The server is safer with writes disabled. ## Per-Account Configuration ### Multiple Accounts Configure multiple IMAP accounts with unique identifiers: ```bash # Default account MAIL_IMAP_DEFAULT_HOST=imap.gmail.com MAIL_IMAP_DEFAULT_USER=user@gmail.com MAIL_IMAP_DEFAULT_PASS=app-password-1 MAIL_IMAP_DEFAULT_PORT=993 MAIL_IMAP_DEFAULT_SECURE=true # Work account MAIL_IMAP_WORK_HOST=outlook.office365.com MAIL_IMAP_WORK_USER=user@company.com MAIL_IMAP_WORK_PASS=app-password-2 MAIL_IMAP_WORK_PORT=993 MAIL_IMAP_WORK_SECURE=true # Personal account MAIL_IMAP_PERSONAL_HOST=imap.fastmail.com MAIL_IMAP_PERSONAL_USER=user@fastmail.com MAIL_IMAP_PERSONAL_PASS=app-password-3 MAIL_IMAP_PERSONAL_PORT=993 MAIL_IMAP_PERSONAL_SECURE=true ``` ### Account ID Rules - Pattern: `^[A-Za-z0-9_-]{1,64}$` - Must be unique across all accounts - `default` is the default account ID if not specified - Examples: `default`, `work`, `personal`, `backup`, `archive` ### Port and Security Standard IMAP configurations: ```bash # IMAPS (implicit TLS) - recommended MAIL_IMAP__PORT=993 MAIL_IMAP__SECURE=true # IMAP with STARTTLS - not supported # Only implicit TLS (IMAPS) is supported ``` ## Environment Variable Priority 1. **Required variables**: Must be set for each account - `MAIL_IMAP__HOST` - `MAIL_IMAP__USER` - `MAIL_IMAP__PASS` 2. **Optional with defaults**: Use defaults if not set - `MAIL_IMAP__PORT=993` - `MAIL_IMAP__SECURE=true` 3. **Server-wide**: Apply globally to all operations - `MAIL_IMAP_WRITE_ENABLED=false` - `MAIL_IMAP_CA_CERT_PATH` unset - `MAIL_IMAP_CONNECT_TIMEOUT_MS=30000` - `MAIL_IMAP_GREETING_TIMEOUT_MS=15000` - `MAIL_IMAP_SOCKET_TIMEOUT_MS=300000` - `MAIL_IMAP_CURSOR_TTL_SECONDS=600` - `MAIL_IMAP_CURSOR_MAX_ENTRIES=512` - `MAIL_IMAP_OPERATION_MAX_ENTRIES=256` ## Trouleshooting Configuration Issues ### Account Not Found ``` Error: invalid input: account "unknown" not configured ``` **Cause:** Account ID does not exist in environment variables. **Resolution:** Check environment variables match requested account ID. Case-sensitive. ### Missing Required Variables ``` Error: missing required environment variable: MAIL_IMAP_DEFAULT_HOST ``` **Cause:** Required configuration not set. **Resolution:** Set all required variables: `HOST`, `USER`, `PASS`. ### Connection Timeout ``` Error: operation timed out: tcp connect timeout ``` **Cause:** Network connectivity or server unreachable. **Resolution:** 1. Verify `MAIL_IMAP__HOST` is correct 2. Check network connectivity to host 3. Increase `MAIL_IMAP_CONNECT_TIMEOUT_MS` 4. Verify firewall allows outbound connections on port 993 ### Authentication Failed ``` Error: authentication failed: [AUTHENTICATIONFAILED] Authentication failed. ``` **Cause:** Invalid credentials or authentication method. **Resolution:** 1. Verify `USER` and `PASS` are correct 2. Use app-specific password for Gmail/Outlook 3. Check account allows IMAP access 4. Verify account not locked or requiring 2FA challenge ## Performance Tuning ### High-Volume Workloads For high-volume operations across large mailboxes: ```bash # Increase cursor capacity MAIL_IMAP_CURSOR_MAX_ENTRIES=1024 # Keep more warm read sessions per account MAIL_IMAP_READ_SESSION_CACHE_MAX_PER_ACCOUNT=8 # Longer cursor TTL for batch processing MAIL_IMAP_CURSOR_TTL_SECONDS=1800 # Longer socket timeout for large searches MAIL_IMAP_SOCKET_TIMEOUT_MS=600000 ``` ### Low-Latency Interactive Use For interactive use with quick responses: ```bash # Shorter timeouts for faster failure detection MAIL_IMAP_CONNECT_TIMEOUT_MS=15000 MAIL_IMAP_GREETING_TIMEOUT_MS=10000 MAIL_IMAP_SOCKET_TIMEOUT_MS=120000 # Keep a smaller idle read-session footprint MAIL_IMAP_READ_SESSION_CACHE_TTL_SECONDS=60 # Fewer stored cursors MAIL_IMAP_CURSOR_MAX_ENTRIES=256 ``` ### Memory-Constrained Environments For environments with limited memory: ```bash # Fewer cursors stored MAIL_IMAP_CURSOR_MAX_ENTRIES=128 # Disable idle read-session reuse entirely MAIL_IMAP_READ_SESSION_CACHE_MAX_PER_ACCOUNT=0 # Shorter cursor TTL MAIL_IMAP_CURSOR_TTL_SECONDS=300 # Tighter timeouts MAIL_IMAP_SOCKET_TIMEOUT_MS=180000 ``` ## Docker-Specific Configuration When running in Docker, ensure environment variables are passed correctly: ```bash docker run --rm -i \ --env-file .env \ -e MAIL_IMAP_CONNECT_TIMEOUT_MS=45000 \ mail-imap-mcp-rs ``` File-based env loading (`--env-file`) takes precedence over `-e` flags.