{"id":26117133,"url":"https://github.com/workingdevshero/deno-imap","last_synced_at":"2026-05-18T00:07:43.874Z","repository":{"id":280200052,"uuid":"941254663","full_name":"workingdevshero/deno-imap","owner":"workingdevshero","description":"🦕📬🦸‍♂️ Heroic IMAP client for Deno","archived":false,"fork":false,"pushed_at":"2025-03-22T21:26:08.000Z","size":187,"stargazers_count":6,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-24T02:35:19.100Z","etag":null,"topics":["deno","email","imap"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workingdevshero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-01T21:12:20.000Z","updated_at":"2025-06-27T16:03:49.000Z","dependencies_parsed_at":"2025-03-18T14:35:51.829Z","dependency_job_id":null,"html_url":"https://github.com/workingdevshero/deno-imap","commit_stats":null,"previous_names":["bobbyg603/deno-imap","workingdevshero/deno-imap"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/workingdevshero/deno-imap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workingdevshero%2Fdeno-imap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workingdevshero%2Fdeno-imap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workingdevshero%2Fdeno-imap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workingdevshero%2Fdeno-imap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workingdevshero","download_url":"https://codeload.github.com/workingdevshero/deno-imap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workingdevshero%2Fdeno-imap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33160168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-17T22:39:12.733Z","status":"ssl_error","status_checked_at":"2026-05-17T22:39:10.741Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deno","email","imap"],"created_at":"2025-03-10T10:58:42.281Z","updated_at":"2026-05-18T00:07:38.860Z","avatar_url":"https://github.com/workingdevshero.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![heroic email delivery](https://github.com/user-attachments/assets/225be12e-9bf9-4faa-a4f2-2f7719fb5254)\n\n# deno-imap\n\nA heroic IMAP (Internet Message Access Protocol) client for Deno.\n\n## Features\n\n- Full IMAP protocol support\n- TLS/SSL support\n- Authentication (PLAIN, LOGIN)\n- Mailbox management (list, create, delete, rename)\n- Message operations (search, fetch, move, copy, delete)\n- Flag management (mark as read/unread, flag/unflag)\n- Comprehensive TypeScript types\n- Promise-based API\n- Utility functions for common operations\n\n## Installation\n\nYou can import the module directly from the JSR registry:\n\n```typescript\nimport { ImapClient } from 'jsr:@workingdevshero/deno-imap';\n```\n\nOr import it from GitHub:\n\n```typescript\nimport { ImapClient } from 'https://raw.githubusercontent.com/workingdevshero/deno-imap/main/mod.ts';\n```\n\n## Basic Usage\n\n```typescript\nimport { ImapClient } from 'jsr:@workingdevshero/deno-imap';\n\n// Create a new IMAP client\nconst client = new ImapClient({\n  host: 'imap.example.com',\n  port: 993,\n  tls: true,\n  username: 'user@example.com',\n  password: 'password',\n});\n\n// Connect and authenticate\nawait client.connect();\nawait client.authenticate();\n\n// List mailboxes\nconst mailboxes = await client.listMailboxes();\nconsole.log('Available mailboxes:', mailboxes);\n\n// Select a mailbox\nconst inbox = await client.selectMailbox('INBOX');\nconsole.log('INBOX has', inbox.exists, 'messages');\n\n// Search for unread messages\nconst unreadMessages = await client.search({ flags: { has: ['\\\\Unseen'] } });\nconsole.log('Unread message IDs:', unreadMessages);\n\n// Fetch messages (safely handling mailboxes with fewer than 10 messages)\nconst messageCount = inbox.exists || 0;\nconst fetchRange = messageCount \u003e 0 ? `1:${Math.min(messageCount, 10)}` : '1';\n\nconst messages = await client.fetch(fetchRange, {\n  envelope: true,\n  headers: ['Subject', 'From', 'Date'],\n});\n\n// Display message details\nfor (const message of messages) {\n  console.log('Message #', message.seq);\n  console.log('Subject:', message.envelope?.subject);\n  console.log(\n    'From:',\n    message.envelope?.from?.[0]?.mailbox + '@' + message.envelope?.from?.[0]?.host,\n  );\n  console.log('Date:', message.envelope?.date);\n}\n\n// Disconnect\nclient.disconnect();\n```\n\n## Using Environment Variables\n\nFor security and flexibility, you can store your IMAP connection details in environment variables:\n\n```typescript\nconst client = new ImapClient({\n  host: Deno.env.get('IMAP_HOST')!,\n  port: parseInt(Deno.env.get('IMAP_PORT')!),\n  tls: Deno.env.get('IMAP_USE_TLS') !== 'false',\n  username: Deno.env.get('IMAP_USERNAME')!,\n  password: Deno.env.get('IMAP_PASSWORD')!,\n});\n```\n\nCreate a `.env` file with your connection details:\n\n```\nIMAP_HOST=\"imap.example.com\"\nIMAP_PORT=993\nIMAP_USERNAME=\"user@example.com\"\nIMAP_PASSWORD=\"your_password_here\"\nIMAP_USE_TLS=\"true\"\n```\n\nThen run your script with the `--env-file` flag:\n\n```bash\ndeno run --allow-net --allow-env --env-file=.env your_script.ts\n```\n\n## Utility Functions\n\nThe package includes utility functions for common operations:\n\n```typescript\nimport {\n  decodeAttachment,\n  deleteMessages,\n  fetchMessagesFromSender,\n  fetchUnreadMessages,\n  hasAttachments,\n  ImapClient,\n  markMessagesAsRead,\n} from 'jsr:@workingdevshero/deno-imap';\n\nconst client = new ImapClient({\n  host: 'imap.example.com',\n  port: 993,\n  tls: true,\n  username: 'user@example.com',\n  password: 'password',\n});\n\nawait client.connect();\nawait client.authenticate();\n\n// Fetch unread messages\nconst unreadMessages = await fetchUnreadMessages(client, 'INBOX');\n\n// Fetch messages from a specific sender\nconst messagesFromSender = await fetchMessagesFromSender(\n  client,\n  'INBOX',\n  'sender@example.com',\n);\n\n// Check if a message has attachments\nfor (const message of unreadMessages) {\n  if (message.bodyStructure \u0026\u0026 hasAttachments(message.bodyStructure)) {\n    console.log(`Message #${message.seq} has attachments`);\n  }\n}\n\n// Mark messages as read using UIDs (more reliable than sequence numbers)\nawait markMessagesAsRead(\n  client,\n  'INBOX',\n  messagesFromSender.map((msg) =\u003e msg.uid || 0).filter((uid) =\u003e uid \u003e 0),\n  true, // Use UIDs instead of sequence numbers\n);\n\n// Delete messages\nawait deleteMessages(\n  client,\n  'INBOX',\n  unreadMessages.slice(0, 5).map((msg) =\u003e msg.uid || 0).filter((uid) =\u003e uid \u003e 0),\n  true, // Use UIDs instead of sequence numbers\n);\n\nclient.disconnect();\n```\n\n## API Reference\n\n### ImapClient\n\nThe main class for interacting with IMAP servers.\n\n#### Constructor\n\n```typescript\nnew ImapClient(options: ImapOptions)\n```\n\n#### Options\n\n- `host`: IMAP server hostname\n- `port`: IMAP server port\n- `tls`: Whether to use TLS (default: true)\n- `username`: Username for authentication\n- `password`: Password for authentication\n- `authMechanism`: Authentication mechanism to use (default: \"PLAIN\")\n- `autoReconnect`: Whether to automatically reconnect on connection loss (default: true)\n- `maxReconnectAttempts`: Maximum number of reconnection attempts (default: 3)\n- `reconnectDelay`: Delay between reconnection attempts in milliseconds (default: 1000)\n- `commandTimeout`: Timeout for commands in milliseconds (default: 30000)\n- `connectionTimeout`: Connection timeout in milliseconds (default: 30000)\n- `socketTimeout`: Socket timeout in milliseconds (default: 60000)\n- `tlsOptions`: TLS options\n\n#### Methods\n\n- `connect()`: Connects to the IMAP server\n- `disconnect()`: Disconnects from the IMAP server\n- `authenticate(mechanism?: ImapAuthMechanism)`: Authenticates with the IMAP server\n- `listMailboxes(reference?: string, mailbox?: string)`: Lists mailboxes\n- `getMailboxStatus(mailbox: string, items?: string[])`: Gets the status of a mailbox\n- `selectMailbox(mailbox: string)`: Selects a mailbox\n- `examineMailbox(mailbox: string)`: Examines a mailbox (read-only mode)\n- `closeMailbox()`: Closes the currently selected mailbox\n- `createMailbox(mailbox: string)`: Creates a new mailbox\n- `deleteMailbox(mailbox: string)`: Deletes a mailbox\n- `renameMailbox(oldName: string, newName: string)`: Renames a mailbox\n- `subscribeMailbox(mailbox: string)`: Subscribes to a mailbox\n- `unsubscribeMailbox(mailbox: string)`: Unsubscribes from a mailbox\n- `search(criteria: ImapSearchCriteria, charset?: string)`: Searches for messages\n- `fetch(sequence: string, options: ImapFetchOptions)`: Fetches messages\n- `setFlags(sequence: string, flags: string[], action?: \"set\" | \"add\" | \"remove\", useUid?: boolean)`:\n  Sets flags on messages\n- `copyMessages(sequence: string, mailbox: string, useUid?: boolean)`: Copies messages to another\n  mailbox\n- `moveMessages(sequence: string, mailbox: string, useUid?: boolean)`: Moves messages to another\n  mailbox\n- `expunge()`: Expunges deleted messages\n- `appendMessage(mailbox: string, message: string, flags?: string[], date?: Date)`: Appends a\n  message to a mailbox\n- `forceReconnect()`: Forces a reconnection to the server\n- `updateCapabilities()`: Updates the server capabilities\n\n#### Properties\n\n- `connected`: Whether the client is connected\n- `authenticated`: Whether the client is authenticated\n- `capabilities`: Server capabilities\n- `selectedMailbox`: Currently selected mailbox\n- `reconnecting`: Whether a reconnection is in progress\n\n### Utility Functions\n\nThe package includes utility functions for common operations:\n\n#### Message Retrieval\n\n- `fetchAllMessages(client: ImapClient, mailbox: string, options?: ImapFetchOptions)`: Fetches all\n  messages in a mailbox\n- `searchAndFetchMessages(client: ImapClient, mailbox: string, criteria: ImapSearchCriteria, options?: ImapFetchOptions)`:\n  Fetches messages matching search criteria\n- `fetchUnreadMessages(client: ImapClient, mailbox: string, options?: ImapFetchOptions)`: Fetches\n  unread messages\n- `fetchMessagesFromSender(client: ImapClient, mailbox: string, sender: string, options?: ImapFetchOptions)`:\n  Fetches messages from a specific sender\n- `fetchMessagesWithSubject(client: ImapClient, mailbox: string, subject: string, options?: ImapFetchOptions)`:\n  Fetches messages with a specific subject\n- `fetchMessagesSince(client: ImapClient, mailbox: string, since: Date, options?: ImapFetchOptions)`:\n  Fetches messages received since a specific date\n- `fetchMessagesWithAttachments(client: ImapClient, mailbox: string, options?: ImapFetchOptions)`:\n  Fetches messages with attachments\n\n#### Message Management\n\n- `markMessagesAsRead(client: ImapClient, mailbox: string, messageIds: number[], useUid?: boolean)`:\n  Marks messages as read\n- `markMessagesAsUnread(client: ImapClient, mailbox: string, messageIds: number[], useUid?: boolean)`:\n  Marks messages as unread\n- `deleteMessages(client: ImapClient, mailbox: string, messageIds: number[], useUid?: boolean)`:\n  Deletes messages\n- `moveMessages(client: ImapClient, sourceMailbox: string, targetMailbox: string, messageIds: number[], useUid?: boolean)`:\n  Moves messages between mailboxes\n\n#### Mailbox Management\n\n- `createMailboxHierarchy(client: ImapClient, path: string, delimiter?: string)`: Creates a mailbox\n  hierarchy\n- `getMailboxHierarchy(client: ImapClient, reference?: string, pattern?: string)`: Gets the mailbox\n  hierarchy\n\n#### Attachment Handling\n\n- `hasAttachments(bodyStructure: ImapBodyStructure)`: Determines if a message has attachments\n- `findAttachments(bodyStructure: ImapBodyStructure, path?: string)`: Extracts detailed information\n  about attachments\n- `decodeAttachment(data: Uint8Array, encoding: string)`: Decodes an attachment based on its\n  encoding\n\n#### Parser Functions\n\n- `parseBodyStructure(data: string)`: Parses a body structure response\n- `parseCapabilities(line: string)`: Parses a capability response\n- `parseEnvelope(data: string)`: Parses an envelope response\n- `parseFetch(lines: string[])`: Parses a fetch response\n- `parseListResponse(line: string)`: Parses a list response\n- `parseSearch(line: string)`: Parses a search response\n- `parseSelect(lines: string[])`: Parses a select response\n- `parseStatus(line: string)`: Parses a status response\n\n### Attachment Handling\n\n#### hasAttachments\n\nDetermines if a message has attachments based on its body structure.\n\n```typescript\nhasAttachments(bodyStructure: ImapBodyStructure): boolean\n```\n\nThis function analyzes the body structure of an email message to determine if it contains\nattachments. It considers the following criteria:\n\n- Parts with explicit `ATTACHMENT` disposition\n- Parts with `INLINE` disposition that have a filename\n- Parts with content types like `APPLICATION`, `IMAGE`, `AUDIO`, or `VIDEO`\n- Parts with a `NAME` parameter\n- `MESSAGE/RFC822` parts without a disposition\n\n#### findAttachments\n\nExtracts detailed information about attachments from a message's body structure.\n\n```typescript\nfindAttachments(bodyStructure: ImapBodyStructure, path?: string): Array\u003c{\n  filename: string;\n  type: string;\n  subtype: string;\n  size: number;\n  encoding: string;\n  section: string;\n}\u003e\n```\n\nThis function analyzes the body structure of an email message and returns an array of attachment\nobjects with detailed information about each attachment, including:\n\n- `filename`: The name of the attachment file\n- `type`: The MIME type (e.g., \"IMAGE\", \"APPLICATION\")\n- `subtype`: The MIME subtype (e.g., \"PNG\", \"PDF\")\n- `size`: The size of the attachment in bytes\n- `encoding`: The content transfer encoding (e.g., \"BASE64\", \"QUOTED-PRINTABLE\")\n- `section`: The IMAP section path used to fetch the attachment\n\n#### decodeAttachment\n\nDecodes an attachment based on its encoding.\n\n```typescript\ndecodeAttachment(data: Uint8Array, encoding: string): Uint8Array\n```\n\nThis function handles different encoding types:\n\n- `BASE64`: Converts base64 to binary\n- `QUOTED-PRINTABLE`: Decodes quoted-printable\n- `7BIT`, `8BIT`, `BINARY`: Returns the data as is (no decoding needed)\n\n## Examples\n\nThe [examples](./examples) directory contains sample code demonstrating how to use the IMAP client:\n\n- [Basic Example](./examples/basic.ts): Demonstrates connecting to an IMAP server, listing\n  mailboxes, and checking the INBOX status.\n- [Search Example](./examples/search.ts): Shows how to search for messages using various criteria.\n- [Fetch Example](./examples/fetch.ts): Demonstrates how to fetch and decode message content,\n  including handling multipart messages and different encodings.\n- [Mailboxes Example](./examples/mailboxes.ts): Shows how to manage mailboxes, including creating,\n  renaming, and deleting them.\n- [Advanced Example](./examples/advanced.ts): Shows more advanced features like searching, fetching\n  message content, and manipulating messages.\n- [Attachments Example](./examples/attachments.ts): Demonstrates how to find messages with\n  attachments, fetch attachment data, properly decode it based on the encoding (BASE64,\n  QUOTED-PRINTABLE, etc.), and save attachments to a local folder.\n\nTo run the examples, create a `.env` file with your IMAP server details, then run:\n\n```bash\n# Run the basic example\ndeno run --allow-net --allow-env --env-file=.env examples/basic.ts\n\n# Run the search example\ndeno run --allow-net --allow-env --env-file=.env examples/search.ts\n\n# Run the fetch example\ndeno run --allow-net --allow-env --env-file=.env examples/fetch.ts\n\n# Run the mailboxes example\ndeno run --allow-net --allow-env --env-file=.env examples/mailboxes.ts\n\n# Run the advanced example\ndeno run --allow-net --allow-env --env-file=.env examples/advanced.ts\n\n# Run the attachments example\ndeno run --allow-net --allow-env --env-file=.env --allow-write --allow-read examples/attachments.ts\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkingdevshero%2Fdeno-imap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkingdevshero%2Fdeno-imap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkingdevshero%2Fdeno-imap/lists"}