feat: implement improvements based on analysis of other implementations

- Add dedicated 'Get Single Email' operation optimized for performance
- Implement ParameterValidator utility class for consistent validation
- Improve error handling with more specific error messages
- Add better type safety and validation across operations
- Optimize content extraction using source: true for better performance
- Version bump to 2.12.0

Author: Derek Zen

CHANGELOG.md

@@ -1,3 +1,18 @@
+## [2.12.0](https://github.com/callzhang/n8n-nodes-imap/compare/v2.11.10...v2.12.0) (2025-01-XX)
+
+### New Features
+
+* **Single Email Operation**: Added dedicated "Get Single Email" operation optimized for fetching individual emails with full content
+* **Parameter Validation**: Implemented consistent parameter validation using ParameterValidator utility class
+* **Enhanced Error Handling**: Improved error messages and validation across all operations
+
+### Improvements
+
+* **Performance Optimization**: Single email operation uses `source: true` for better content extraction
+* **Better Type Safety**: Added proper TypeScript interfaces and validation
+* **Cleaner Code Structure**: Separated concerns with dedicated utility classes
+* **Consistent Validation**: Standardized parameter validation across all operations
+
 ## [2.11.10](https://github.com/callzhang/n8n-nodes-imap/compare/v2.11.9...v2.11.10) (2025-01-XX)
 
 ### Bug Fixes

getEmail.ts

@@ -0,0 +1,125 @@
+import { ImapFlow } from 'imapflow';
+import { ParsedMail, simpleParser } from 'mailparser';
+import { IExecuteFunctions, NodeApiError } from 'n8n-workflow';
+import { ParameterValidator } from '../utils/helpers';
+import { IEmailData, IImapOperation } from '../utils/types';
+
+export class GetEmailOperation implements IImapOperation {
+	async execute(
+		executeFunctions: IExecuteFunctions,
+		client: ImapFlow,
+		itemIndex: number,
+	): Promise<IEmailData> {
+		const mailboxParam = executeFunctions.getNodeParameter('mailbox', itemIndex) as string | { mode: string; value: string };
+		const mailbox = ParameterValidator.extractMailboxName(mailboxParam);
+		const emailUid = executeFunctions.getNodeParameter('emailUid', itemIndex) as string;
+
+		ParameterValidator.validateMailbox(mailboxParam);
+		ParameterValidator.validateUid(emailUid);
+
+		try {
+			await client.mailboxOpen(mailbox);
+		} catch (error) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Failed to open folder ${mailbox}: ${(error as Error).message}`,
+			});
+		}
+
+												let message: any;
+		try {
+			// First, search for the specific UID to verify it exists
+			const searchResults = await client.search({ uid: emailUid.toString() });
+			if (searchResults.length === 0) {
+				throw new NodeApiError(executeFunctions.getNode(), {
+					message: `Email with UID ${emailUid} not found in ${mailbox}`,
+				});
+			}
+
+			// Fetch full email content but skip attachment processing
+			const messageGenerator = client.fetch(emailUid.toString(), {
+				source: true,  // Full email source for text/html content
+				uid: true,
+				flags: true,
+				size: true
+			}, { uid: true });
+
+			// Get the first (and only) message from the generator
+			for await (const msg of messageGenerator) {
+				message = msg;
+				break;
+			}
+
+			if (!message) {
+				throw new Error(`No message data received for UID ${emailUid}`);
+			}
+		} catch (error) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Failed to fetch email with UID ${emailUid}: ${(error as Error).message}`,
+			});
+		}
+
+		if (!message) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Email with UID ${emailUid} not found in ${mailbox}`,
+			});
+		}
+
+				// Parse email content but skip attachments
+		if (!message.source) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Email source not available for UID ${emailUid}`,
+			});
+		}
+
+		let parsed: ParsedMail;
+		try {
+			// Parse email content (will include attachments info but we'll ignore them)
+			parsed = await simpleParser(message.source);
+			console.log('Email parsed successfully:', {
+				subject: parsed.subject,
+				fromCount: parsed.from ? 1 : 0,
+				textLength: typeof parsed.text === 'string' ? parsed.text.length : 0,
+				htmlLength: typeof parsed.html === 'string' ? parsed.html.length : 0
+			});
+		} catch (error) {
+			console.error('Email parsing failed:', error);
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Failed to parse email content: ${(error as Error).message}`,
+			});
+		}
+
+		// Helper function to normalize address objects to arrays
+		const normalizeAddresses = (addresses: any): any[] => {
+			if (!addresses) return [];
+			return Array.isArray(addresses) ? addresses : [addresses];
+		};
+
+		// Return email data with content but NO attachments
+		const emailData: IEmailData = {
+			uid: typeof message.uid === 'string' ? parseInt(message.uid, 10) : message.uid,
+			subject: parsed.subject || '',
+			from: parsed.from || {},
+			to: normalizeAddresses(parsed.to),
+			cc: normalizeAddresses(parsed.cc),
+			bcc: normalizeAddresses(parsed.bcc),
+			date: parsed.date || null,
+			text: parsed.text || '',    // Full text content
+			html: parsed.html || '',    // Full HTML content
+			attachments: [],  // NO attachments - use downloadAttachment operation instead
+			flags: message.flags || new Set(),
+			seen: message.flags?.has('\\Seen') || false,
+			size: message.size
+		};
+
+		console.log('Email data prepared for return:', {
+			uid: emailData.uid,
+			subject: emailData.subject,
+			from: emailData.from,
+			textLength: emailData.text?.length || 0,
+			htmlLength: emailData.html?.length || 0,
+			flagsCount: emailData.flags.size
+		});
+
+		return emailData;
+	}
+}

markEmail.ts

@@ -0,0 +1,63 @@
+import { ImapFlow } from 'imapflow';
+import { IExecuteFunctions, NodeApiError, INodeExecutionData } from 'n8n-workflow';
+import { ParameterValidator } from '../utils/helpers';
+import { IImapOperation } from '../utils/types';
+
+export class MarkEmailOperation implements IImapOperation {
+	async execute(
+		executeFunctions: IExecuteFunctions,
+		client: ImapFlow,
+		itemIndex: number,
+	): Promise<INodeExecutionData[]> {
+		const mailboxParam = executeFunctions.getNodeParameter('mailbox', itemIndex) as string | { mode: string; value: string };
+		const mailbox = ParameterValidator.extractMailboxName(mailboxParam);
+		const emailUid = executeFunctions.getNodeParameter('emailUid', itemIndex) as string;
+		const markAs = executeFunctions.getNodeParameter('markAs', itemIndex) as string;
+
+		ParameterValidator.validateMailbox(mailboxParam);
+		ParameterValidator.validateUid(emailUid);
+
+		const returnData: INodeExecutionData[] = [];
+
+		executeFunctions.logger?.info(`Marking email "${emailUid}" as ${markAs} in "${mailbox}"`);
+
+		try {
+			await client.mailboxOpen(mailbox, { readOnly: false });
+		} catch (error) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Failed to open mailbox ${mailbox}: ${(error as Error).message}`,
+			});
+		}
+
+		try {
+			let result: boolean;
+			if (markAs === 'read') {
+				result = await client.messageFlagsAdd(emailUid, ['\\Seen'], { uid: true });
+			} else {
+				result = await client.messageFlagsRemove(emailUid, ['\\Seen'], { uid: true });
+			}
+
+			if (!result) {
+				throw new NodeApiError(executeFunctions.getNode(), {
+					message: "Unable to mark email - no response from server",
+				});
+			}
+
+			const jsonData = {
+				success: true,
+				message: `Email marked as ${markAs}`,
+				uid: emailUid,
+			};
+
+			returnData.push({
+				json: jsonData,
+			});
+
+			return returnData;
+		} catch (error) {
+			throw new NodeApiError(executeFunctions.getNode(), {
+				message: `Failed to mark email: ${(error as Error).message}`,
+			});
+		}
+	}
+}

nodes/Imap/operations/email/OperationsList.ts

@@ -5,6 +5,7 @@ import { createDraftOperation } from './functions/EmailCreateDraft';
 import { downloadOperation } from './functions/EmailDownload';
 import { downloadAttachmentOperation } from './functions/EmailDownloadAttachment';
 import { getEmailsListOperation } from './functions/EmailGetList';
+import { getSingleEmailOperation } from './functions/EmailGetSingle';
 import { moveEmailOperation } from './functions/EmailMove';
 import { setEmailFlagsOperation } from './functions/EmailSetFlags';
 import { manageEmailLabelsOperation } from './functions/EmailManageLabels';
@@ -13,6 +14,7 @@ export const emailResourceDefinitions: IResourceDef = {
 	resource: resourceEmail,
 	operationDefs: [
 		getEmailsListOperation,
+		getSingleEmailOperation,
 		downloadOperation,
 		downloadAttachmentOperation,
 		moveEmailOperation,

nodes/Imap/operations/email/functions/EmailGetList.ts

@@ -322,7 +322,7 @@ export const getEmailsListOperation: IResourceOperationDef = {
           if (rawMessage.content) {
             const rawContent = await streamToString(rawMessage.content);
             const parsed = await simpleParser(rawContent);
-            
+
             // Create envelope-like structure from parsed data
             item_json.envelope = {
               subject: parsed.subject || '',
@@ -335,13 +335,13 @@ export const getEmailsListOperation: IResourceOperationDef = {
               messageId: parsed.messageId || '',
               inReplyTo: parsed.inReplyTo || ''
             };
-            
+
             // Set flags to empty array if not available
             item_json.labels = [];
-            
+
             // Set size from parsed data
             item_json.size = rawContent.length;
-            
+
             context.logger?.debug(`Raw message parsing successful for email ${email.uid}`);
           }
         } catch (error) {
@@ -481,14 +481,14 @@ export const getEmailsListOperation: IResourceOperationDef = {
           if (rawMessage.content) {
             const rawContent = await streamToString(rawMessage.content);
             const parsed = await simpleParser(rawContent);
-            
+
             // Extract content from parsed data
             if (parsed.text) {
               item_json.text = parsed.text;
               item_json.markdown = parsed.text; // Plain text is already readable
               item_json.html = textToSimplifiedHtml(parsed.text);
             }
-            
+
             if (parsed.html) {
               item_json.html = parsed.html;
               item_json.markdown = htmlToMarkdown(parsed.html);
@@ -497,14 +497,14 @@ export const getEmailsListOperation: IResourceOperationDef = {
                 item_json.text = htmlToText(parsed.html);
               }
             }
-            
+
             // If still no content, set empty values
             if (!item_json.text && !item_json.html) {
               item_json.text = '';
               item_json.markdown = '';
               item_json.html = '';
             }
-            
+
             context.logger?.debug(`Raw message body parsing successful for email ${email.uid}`);
           }
         } catch (error) {