read-email-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KelpHect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,203 @@
+# Read Email MCP
+
+A read-only [Model Context Protocol](https://modelcontextprotocol.io) server that mirrors any IMAP mailbox into a local SQLite database, then lets AI clients browse, search, and read email without reconnecting to the server on every request.
+
+It works with Gmail, Outlook, Yahoo, Fastmail, iCloud, Proton Mail Bridge, self-hosted mail, and any other provider that exposes standard IMAP.
+
+> **Version 1.0.0-rc.1** release candidate. The tool surface and configuration are stable for review. Please report issues.
+
+## Why use it
+
+- **Fast browsing and search.** Email is synced once into a local SQLite mirror with full-text search. Every browse, search, and read call hits the local copy, so it is quick and never re-logs-in to IMAP per request.
+- **Read-only and safe.** It never sends, deletes, moves, flags, or marks messages. IMAP mailboxes are opened with read-only locks. Your mailbox cannot be mutated by this server.
+- **Provider agnostic.** Point it at any IMAP server with host, port, and TLS settings. No vendor lock-in.
+- **Private by design.** Credentials stay in the process environment. Passwords are never written to disk. Raw `.eml` files live under your home directory and never leave your machine.
+- **MCP native.** Exposes a clean set of tools over stdio so any MCP-compatible client can read email on your behalf.
+
+## Requirements
+
+- Node.js 20 or newer
+- A mailbox with IMAP enabled
+- The mailbox email address and password. Most consumer providers (Gmail, Yahoo, iCloud, Outlook with 2FA) require an **app-specific password** instead of your normal sign-in password.
+
+## Quick start
+
+```powershell
+git clone <this-repo>
+cd read-email-mcp
+npm install
+npm run build
+```
+
+Run the server with credentials and an IMAP host:
+
+```powershell
+node dist/index.js `
+  --email "you@gmail.com" `
+  --password "your-app-password" `
+  --imap-host "imap.gmail.com"
+```
+
+Or set environment variables and omit the flags:
+
+```powershell
+$env:EMAIL = "you@gmail.com"
+$env:PASSWORD = "your-app-password"
+$env:IMAP_HOST = "imap.gmail.com"
+node dist/index.js
+```
+
+## Configuration
+
+All settings can be passed as CLI args or environment variables. CLI args take precedence over environment variables.
+
+| Setting | Required | Env var | CLI arg | Default |
+| --- | --- | --- | --- | --- |
+| Email address | yes | `EMAIL` | `--email` | none |
+| Password | yes | `PASSWORD` | `--password` | none |
+| IMAP host | yes | `IMAP_HOST` | `--imap-host` | none |
+| IMAP port | no | `IMAP_PORT` | `--imap-port` | `993` |
+| IMAP TLS | no | `IMAP_SECURE` | `--imap-secure` | `true` |
+| IMAP login user | no | `IMAP_USER` | `--imap-user` | same as email |
+
+`IMAP_SECURE` accepts `true` or `false` (also `1`/`0`, `yes`/`no`, `on`/`off`). Use `false` with port `143` for STARTTLS or plain IMAP.
+
+`IMAP_USER` is optional. Set it only when the IMAP login name differs from the mailbox email address. When omitted, the email address is used as the IMAP username.
+
+### Common provider settings
+
+| Provider | IMAP host | Port | TLS | Notes |
+| --- | --- | --- | --- | --- |
+| Gmail | `imap.gmail.com` | 993 | true | Needs an app password with 2FA enabled |
+| Outlook / Office 365 | `outlook.office365.com` | 993 | true | Use your Microsoft account password or app password |
+| Yahoo | `imap.mail.yahoo.com` | 993 | true | Needs an app password |
+| iCloud | `imap.mail.me.com` | 993 | true | Needs an app password |
+| Fastmail | `imap.fastmail.com` | 993 | true | Use your Fastmail app password |
+| Proton Mail | `127.0.0.1` | 1143 | false | Requires the Proton Mail Bridge app running locally |
+| Self-hosted | your mail server | 993 or 143 | true or false | Depends on your server config |
+
+## MCP client configuration
+
+The server speaks MCP over stdio. Add it to any MCP-compatible client.
+
+### Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "read-email": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "read-email-mcp@1.0.0-rc.1",
+        "--email",
+        "you@gmail.com",
+        "--password",
+        "your-app-password",
+        "--imap-host",
+        "imap.gmail.com"
+      ]
+    }
+  }
+}
+```
+
+### Codex CLI and other env-based clients
+
+Set credentials in the server environment and pass only the binary:
+
+```json
+{
+  "mcpServers": {
+    "read-email": {
+      "command": "npx",
+      "args": ["-y", "read-email-mcp@1.0.0-rc.1"],
+      "env": {
+        "EMAIL": "you@gmail.com",
+        "PASSWORD": "your-app-password",
+        "IMAP_HOST": "imap.gmail.com"
+      }
+    }
+  }
+}
+```
+
+> On npm, pre-release versions like `1.0.0-rc.1` are not selected by `@latest`. Pin the exact version as shown above, or install from source after building.
+
+## Tools
+
+The server exposes 12 tools. All read from the local mirror except `sync_email`, which pulls from IMAP.
+
+- `sync_email`: pull new messages from IMAP into the local mirror. Call this first, or after a gap, before browsing or searching. Start with a small limit on one mailbox to verify credentials, then sync more.
+- `get_sync_status`: show account, storage path, total messages, latest message date, per-mailbox counts, and the last sync result. Good first check to see whether a sync is needed.
+- `list_mailboxes`: list locally known mailboxes (INBOX, Sent, Drafts, and so on) with message counts and last-sync time.
+- `get_recent_emails`: show the latest emails, newest first, with optional `unreadOnly` and `flaggedOnly`. This is the everyday tool for checking what is new.
+- `browse_email_dates`: summarize message volume as counts per day, week, or month. Useful for finding a busy period before drilling in with a date range.
+- `search_emails`: full-text search across subject, sender and recipient addresses, preview, and body, with filters and keyset pagination.
+- `list_emails`: list email summaries in chronological order with filters and pagination, without full-text search. Prefer this when browsing by sender, date, or mailbox.
+- `get_email`: return full metadata and body (text and HTML) for a single message, by id, Message-ID, or mailbox plus UID.
+- `get_thread`: return all locally known messages in one conversation, matched by Message-ID, In-Reply-To, and References headers.
+- `get_raw_email`: return raw RFC822/MIME source for one message, byte-limited. Use this only when you need original headers or MIME structure.
+- `get_storage_stats`: report SQLite database, WAL, and page statistics for the local mirror.
+- `optimize_email_store`: run lightweight SQLite and FTS maintenance to keep queries fast. Safe to run after large syncs.
+
+`search_emails`, `list_emails`, and `get_recent_emails` accept unread and flagged filters. `search_emails` and `list_emails` use `limit`, `cursor`, and `nextCursor` for keyset pagination.
+
+## Typical workflow
+
+1. Run `sync_email` with a small limit on one mailbox to verify credentials.
+2. Run `get_sync_status` to confirm the mirror is fresh.
+3. Run `get_recent_emails` with `unreadOnly: true` to see what is new.
+4. Run `get_email` to read a message, or `get_thread` to follow a conversation.
+5. Run `search_emails` or `list_emails` to find older messages by sender, subject, date range, or unread and flagged state.
+
+## How sync works
+
+Sync connects to IMAP, lists selectable mailboxes, and fetches new messages by tracking the highest UID already seen per mailbox. If a mailbox UIDVALIDITY changes, the local copy for that mailbox is reset and refetched. Raw RFC822 source is written to disk, parsed metadata and body text go into SQLite, and a full-text search index is maintained alongside.
+
+Sync is incremental. Subsequent calls only fetch messages with UIDs higher than the stored high-water mark. Mailboxes are opened read-only, so flags and read state on the server are never changed.
+
+## Local storage
+
+The mirror is stored under:
+
+```text
+~/.read-email-mcp/<account-hash>/
+  emails.sqlite
+  raw/
+```
+
+The account hash is derived from the email address, so multiple accounts coexist without exposing the address in folder names. Passwords are never written to disk.
+
+Raw `.eml` files contain full email content. Treat the storage directory as sensitive and protect it the same way you protect your mailbox.
+
+## Safety
+
+- The server is read-only. It does not send, delete, move, archive, mark read, or mutate flags.
+- IMAP mailboxes are opened with read-only locks during sync.
+- Credentials live only in the process environment and are never persisted by this server.
+- The SQLite mirror uses WAL mode, a busy timeout, keyset pagination, and periodic FTS optimization for local performance and concurrency.
+
+## Development
+
+```powershell
+npm test          # unit tests (no real mailbox needed)
+npm run typecheck # TypeScript checks
+npm run build     # compile to dist/
+npm run smoke:mcp # start the built server over stdio and verify all tools
+npm run verify    # runs all of the above
+```
+
+Tests use fixtures and fake IMAP clients, so they do not require real credentials or a live mail server.
+
+## Limitations
+
+- No sending, replying, or composing email.
+- No deleting, moving, flagging, or marking messages read.
+- No OAuth. App passwords or direct passwords only.
+- No background daemon. Sync runs when the client calls `sync_email`.
+- Attachment bytes are summarized but not extracted to separate files.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+export interface AppConfig {
+    account: {
+        email: string;
+        accountHash: string;
+    };
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+        auth: {
+            user: string;
+            pass: string;
+        };
+    };
+    storage: {
+        baseDir: string;
+        accountDir: string;
+        databasePath: string;
+        rawDir: string;
+    };
+}
+interface LoadConfigOptions {
+    dataDir?: string;
+    args?: string[];
+}
+export declare const DEFAULT_IMAP_PORT = 993;
+export declare const DEFAULT_IMAP_SECURE = true;
+export declare function hashAccount(email: string): string;
+export declare function loadConfig(env?: NodeJS.ProcessEnv, options?: LoadConfigOptions): AppConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,99 @@
+import crypto from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+export const DEFAULT_IMAP_PORT = 993;
+export const DEFAULT_IMAP_SECURE = true;
+export function hashAccount(email) {
+    return crypto
+        .createHash("sha256")
+        .update(email.trim().toLowerCase())
+        .digest("hex")
+        .slice(0, 16);
+}
+export function loadConfig(env = process.env, options = {}) {
+    const args = options.args ?? process.argv.slice(2);
+    const argEmail = getArgValue(args, "--email");
+    const argPassword = getArgValue(args, "--password");
+    const argImapHost = getArgValue(args, "--imap-host");
+    const argImapPort = getArgValue(args, "--imap-port");
+    const argImapSecure = getArgValue(args, "--imap-secure");
+    const argImapUser = getArgValue(args, "--imap-user");
+    const email = (argEmail ?? env.EMAIL)?.trim().toLowerCase();
+    const password = argPassword ?? env.PASSWORD;
+    if (!email) {
+        throw new Error("Missing required credential: provide --email or EMAIL");
+    }
+    if (!password) {
+        throw new Error("Missing required credential: provide --password or PASSWORD");
+    }
+    const host = (argImapHost ?? env.IMAP_HOST)?.trim();
+    if (!host) {
+        throw new Error("Missing required IMAP setting: provide --imap-host or IMAP_HOST (for example imap.gmail.com)");
+    }
+    const port = parsePort(argImapPort ?? env.IMAP_PORT ?? DEFAULT_IMAP_PORT);
+    const secure = parseBoolean(argImapSecure ?? env.IMAP_SECURE, DEFAULT_IMAP_SECURE);
+    const customImapUser = argImapUser ?? env.IMAP_USER;
+    const authUser = customImapUser && customImapUser.trim() ? customImapUser.trim() : email;
+    const accountHash = hashAccount(email);
+    const baseDir = options.dataDir ?? path.join(os.homedir(), ".read-email-mcp");
+    const accountDir = path.join(baseDir, accountHash);
+    return {
+        account: {
+            email,
+            accountHash
+        },
+        imap: {
+            host,
+            port,
+            secure,
+            auth: {
+                user: authUser,
+                pass: password
+            }
+        },
+        storage: {
+            baseDir,
+            accountDir,
+            databasePath: path.join(accountDir, "emails.sqlite"),
+            rawDir: path.join(accountDir, "raw")
+        }
+    };
+}
+function parsePort(value) {
+    if (value === undefined || value === "") {
+        return DEFAULT_IMAP_PORT;
+    }
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`Invalid IMAP port: ${String(value)}. Expected an integer between 1 and 65535.`);
+    }
+    return port;
+}
+function parseBoolean(value, fallback) {
+    if (value === undefined || value === "") {
+        return fallback;
+    }
+    const normalized = value.trim().toLowerCase();
+    if (["true", "1", "yes", "on"].includes(normalized)) {
+        return true;
+    }
+    if (["false", "0", "no", "off"].includes(normalized)) {
+        return false;
+    }
+    throw new Error(`Invalid IMAP secure value: ${value}. Expected true or false.`);
+}
+function getArgValue(args, ...names) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        for (const name of names) {
+            if (arg === name) {
+                return args[index + 1];
+            }
+            if (arg.startsWith(`${name}=`)) {
+                return arg.slice(name.length + 1);
+            }
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/imap.d.ts

@@ -0,0 +1,60 @@
+import type { AppConfig } from "./config.js";
+import type { EmailStore } from "./store.js";
+import type { SyncResultRecord } from "./types.js";
+export interface ImapMailboxInfo {
+    path: string;
+    delimiter?: string;
+    flags?: Iterable<string>;
+}
+export interface ImapFetchMessage {
+    uid: number;
+    source: Buffer | Uint8Array | string;
+    internalDate?: Date | string;
+    flags?: Iterable<string>;
+    size?: number;
+}
+export interface ImapClientLike {
+    connect(): Promise<void>;
+    logout(): Promise<void>;
+    list(): Iterable<ImapMailboxInfo> | AsyncIterable<ImapMailboxInfo> | Promise<Iterable<ImapMailboxInfo> | AsyncIterable<ImapMailboxInfo>>;
+    mailbox?: {
+        uidValidity?: string | number | bigint;
+        uidNext?: number;
+        exists?: number;
+    };
+    getMailboxLock(mailbox: string, options?: {
+        readOnly?: boolean;
+        description?: string;
+    }): Promise<{
+        path: string;
+        uidValidity?: string | number | bigint;
+        uidNext?: number;
+        exists?: number;
+        release(): void;
+    }>;
+    fetch(range: string, query?: unknown, options?: unknown): AsyncIterable<ImapFetchMessage>;
+}
+export type ImapClientFactory = (config: AppConfig["imap"]) => ImapClientLike;
+export interface EmailSyncServiceOptions {
+    imap: AppConfig["imap"];
+    rawDir: string;
+    store: EmailStore;
+    clientFactory?: ImapClientFactory;
+}
+export interface SyncOptions {
+    mailbox?: string;
+    limit?: number;
+    since?: string;
+}
+export interface SyncResult extends SyncResultRecord {
+    mailboxes: string[];
+}
+export declare class EmailSyncService {
+    private readonly options;
+    private readonly clientFactory;
+    constructor(options: EmailSyncServiceOptions);
+    sync(syncOptions?: SyncOptions): Promise<SyncResult>;
+    private selectMailboxes;
+    private syncMailbox;
+    private writeRawEmail;
+}

package/dist/imap.js

@@ -0,0 +1,255 @@
+import { ImapFlow } from "imapflow";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { parseEmail } from "./parser.js";
+export class EmailSyncService {
+    options;
+    clientFactory;
+    constructor(options) {
+        this.options = options;
+        this.clientFactory = options.clientFactory ?? createImapFlowClient;
+    }
+    async sync(syncOptions = {}) {
+        const startedAt = new Date().toISOString();
+        const client = this.clientFactory(this.options.imap);
+        let connected = false;
+        const syncedMailboxes = [];
+        let syncedMessages = 0;
+        try {
+            await client.connect();
+            connected = true;
+            const mailboxes = await this.selectMailboxes(client, syncOptions.mailbox);
+            for (const mailbox of mailboxes) {
+                if (syncOptions.limit !== undefined && syncedMessages >= syncOptions.limit) {
+                    break;
+                }
+                syncedMailboxes.push(mailbox.path);
+                const syncedForMailbox = await this.syncMailbox(client, mailbox, syncOptions, syncedMessages);
+                syncedMessages += syncedForMailbox;
+            }
+            const result = {
+                ok: true,
+                mailbox: syncOptions.mailbox ?? null,
+                startedAt,
+                finishedAt: new Date().toISOString(),
+                message: `Synced ${syncedMessages} message${syncedMessages === 1 ? "" : "s"}`,
+                syncedMessages,
+                mailboxes: syncedMailboxes
+            };
+            this.options.store.recordSyncResult(result);
+            return result;
+        }
+        catch (error) {
+            const result = {
+                ok: false,
+                mailbox: syncOptions.mailbox ?? null,
+                startedAt,
+                finishedAt: new Date().toISOString(),
+                message: error instanceof Error ? error.message : String(error),
+                syncedMessages,
+                mailboxes: syncedMailboxes
+            };
+            this.options.store.recordSyncResult(result);
+            return result;
+        }
+        finally {
+            if (connected) {
+                await client.logout();
+            }
+        }
+    }
+    async selectMailboxes(client, requestedMailbox) {
+        const mailboxes = [];
+        const mailboxList = await client.list();
+        for await (const mailbox of mailboxList) {
+            const flags = [...(mailbox.flags ?? [])];
+            if (flags.includes("\\Noselect")) {
+                continue;
+            }
+            if (requestedMailbox && mailbox.path !== requestedMailbox) {
+                continue;
+            }
+            mailboxes.push({
+                path: mailbox.path,
+                delimiter: mailbox.delimiter ?? "/",
+                flags
+            });
+        }
+        if (requestedMailbox && mailboxes.length === 0) {
+            mailboxes.push({ path: requestedMailbox, delimiter: "/", flags: [] });
+        }
+        return mailboxes;
+    }
+    async syncMailbox(client, mailbox, syncOptions, alreadySynced) {
+        const lock = await client.getMailboxLock(mailbox.path, {
+            readOnly: true,
+            description: "read-email-mcp read-only sync"
+        });
+        try {
+            const mailboxState = getMailboxSyncState(lock, client);
+            const uidValidity = mailboxState.uidValidity;
+            const existing = this.options.store.getMailbox(mailbox.path);
+            const uidValidityChanged = Boolean(existing?.uidValidity && existing.uidValidity !== uidValidity);
+            const startUid = uidValidityChanged ? 1 : (existing?.highestUid ?? 0) + 1;
+            let highestUid = uidValidityChanged ? 0 : existing?.highestUid ?? 0;
+            let count = 0;
+            if (uidValidityChanged) {
+                this.options.store.deleteMailboxMessages(mailbox.path);
+            }
+            this.options.store.upsertMailbox({
+                path: mailbox.path,
+                delimiter: mailbox.delimiter,
+                uidValidity,
+                highestUid,
+                selectable: true,
+                lastSyncedAt: existing?.lastSyncedAt ?? null
+            });
+            const fetchPlan = buildFetchPlan(startUid, syncOptions, alreadySynced, mailboxState.maxUid);
+            if (!fetchPlan) {
+                this.options.store.upsertMailbox({
+                    path: mailbox.path,
+                    delimiter: mailbox.delimiter,
+                    uidValidity,
+                    highestUid: Math.max(highestUid, mailboxState.maxUid ?? highestUid),
+                    selectable: true,
+                    lastSyncedAt: new Date().toISOString()
+                });
+                return 0;
+            }
+            for await (const fetched of client.fetch(fetchPlan.range, { source: true, uid: true, flags: true, internalDate: true, size: true }, { uid: true })) {
+                if (syncOptions.limit !== undefined && alreadySynced + count >= syncOptions.limit) {
+                    break;
+                }
+                highestUid = Math.max(highestUid, fetched.uid);
+                const internalDate = normalizeInternalDate(fetched.internalDate);
+                if (syncOptions.since && internalDate && internalDate < syncOptions.since) {
+                    continue;
+                }
+                const raw = Buffer.isBuffer(fetched.source) ? fetched.source : Buffer.from(fetched.source);
+                const rawPath = await this.writeRawEmail(mailbox.path, uidValidity, fetched.uid, raw);
+                const parsed = await parseFetchedEmail(raw, {
+                    mailbox: mailbox.path,
+                    uid: fetched.uid,
+                    uidValidity,
+                    rawPath,
+                    internalDate,
+                    flags: [...(fetched.flags ?? [])],
+                    size: fetched.size ?? raw.length
+                });
+                this.options.store.upsertMessage(parsed);
+                count += 1;
+            }
+            this.options.store.upsertMailbox({
+                path: mailbox.path,
+                delimiter: mailbox.delimiter,
+                uidValidity,
+                highestUid: Math.max(highestUid, fetchPlan.scannedThroughUid ?? highestUid),
+                selectable: true,
+                lastSyncedAt: new Date().toISOString()
+            });
+            return count;
+        }
+        finally {
+            lock.release();
+        }
+    }
+    async writeRawEmail(mailbox, uidValidity, uid, raw) {
+        const mailboxDir = path.join(this.options.rawDir, hashMailbox(mailbox));
+        await fs.mkdir(mailboxDir, { recursive: true });
+        const rawPath = path.join(mailboxDir, `${safeSegment(uidValidity || "unknown")}-${uid}.eml`);
+        await fs.writeFile(rawPath, raw);
+        return rawPath;
+    }
+}
+function createImapFlowClient(config) {
+    return new ImapFlow({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: config.auth,
+        logger: false
+    });
+}
+function getMailboxSyncState(lock, client) {
+    const uidNext = normalizeUidNumber(lock.uidNext ?? client.mailbox?.uidNext);
+    return {
+        uidValidity: String(lock.uidValidity ?? client.mailbox?.uidValidity ?? ""),
+        maxUid: uidNext === null ? null : Math.max(uidNext - 1, 0)
+    };
+}
+function buildFetchPlan(startUid, syncOptions, alreadySynced, maxUid) {
+    if (maxUid !== null && startUid > maxUid) {
+        return null;
+    }
+    const remaining = syncOptions.limit === undefined ? null : syncOptions.limit - alreadySynced;
+    if (remaining !== null && remaining <= 0) {
+        return null;
+    }
+    let endUid;
+    if (remaining === null) {
+        endUid = maxUid ?? "*";
+    }
+    else {
+        endUid = startUid + remaining - 1;
+        if (maxUid !== null) {
+            endUid = Math.min(endUid, maxUid);
+        }
+    }
+    return {
+        range: `${startUid}:${endUid}`,
+        scannedThroughUid: typeof endUid === "number" && maxUid !== null ? endUid : undefined
+    };
+}
+function normalizeUidNumber(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return null;
+    }
+    return Math.max(Math.trunc(value), 0);
+}
+async function parseFetchedEmail(raw, context) {
+    try {
+        return await parseEmail(raw, context);
+    }
+    catch (error) {
+        return {
+            mailbox: context.mailbox,
+            uid: context.uid,
+            uidValidity: context.uidValidity,
+            messageId: null,
+            inReplyTo: null,
+            references: [],
+            subject: null,
+            date: context.internalDate ?? new Date(0).toISOString(),
+            internalDate: context.internalDate,
+            from: [],
+            to: [],
+            cc: [],
+            bcc: [],
+            flags: context.flags,
+            size: context.size,
+            hasAttachments: false,
+            attachmentCount: 0,
+            preview: null,
+            text: null,
+            html: null,
+            headers: {},
+            attachments: [],
+            rawPath: context.rawPath,
+            parseError: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function normalizeInternalDate(value) {
+    if (!value) {
+        return null;
+    }
+    return value instanceof Date ? value.toISOString() : new Date(value).toISOString();
+}
+function hashMailbox(mailbox) {
+    return crypto.createHash("sha256").update(mailbox).digest("hex").slice(0, 16);
+}
+function safeSegment(value) {
+    return value.replace(/[^a-zA-Z0-9_.-]/g, "_");
+}
+//# sourceMappingURL=imap.js.map