Overview
This node connects to an IMAP email server and retrieves emails from a specified mailbox. It supports filtering emails by read status, date range, sender, recipient, subject content, and attachment presence. Users can limit the number of emails returned and choose whether to include the email body and attachments in the output.
Common scenarios for this node include:
- Automatically fetching unread emails from an inbox for processing or archiving.
- Filtering emails from specific senders or with certain subjects for automated workflows.
- Extracting attachments from emails for further handling.
- Monitoring a mailbox for new messages within a given date range.
Example use cases:
- A support system that fetches unread customer emails to create tickets.
- An automation that downloads invoices attached to emails from a finance mailbox.
- A workflow that filters emails sent to a marketing address containing specific keywords.
Properties
| Name | Meaning |
|---|---|
| Mailbox | Mailbox to search in (e.g., INBOX, Sent) |
| Limit | Max number of results to return (minimum 1) |
| Read Status | Filter emails by read status: All, Unread Only, or Read Only |
| Additional Options | Collection of optional filters and settings: |
| - Date From | Only get emails newer than this date |
| - Date To | Only get emails older than this date |
| - From Filter | Filter emails from a specific sender |
| - Has Attachments | Whether to filter emails that have attachments |
| - Include Attachments | Whether to include attachment data in the output |
| - Include Body | Whether to include email body content (text and HTML) |
| - Subject Filter | Filter emails containing this text in the subject |
| - To Filter | Filter emails sent to a specific recipient |
Output
The node outputs an array of JSON objects representing emails matching the criteria. Each email object contains:
uid: Unique identifier of the email on the server.messageId: The message ID header.subject: Email subject line.from: Sender's email address as text.to: Recipient(s) email addresses as text.cc: CC recipients as text.bcc: BCC recipients as text.date: Date the email was sent.flags: Array of flags set on the email (e.g., \Seen).isRead: Boolean indicating if the email is marked as read.hasAttachments: Boolean indicating if the email has attachments.attachmentCount: Number of attachments.bodyText: Plain text body of the email (included if enabled).bodyHtml: HTML body of the email (included if enabled).attachments(optional): Array of attachments, each with:filenamecontentTypesizecontent: Base64 encoded content of the attachment (if included).
If the node encounters errors during execution and "Continue On Fail" is enabled, it outputs error information per item.
Dependencies
- Requires connection credentials to an IMAP server including email, password, host, port, and TLS settings.
- Uses the
imaplibrary to connect and fetch emails. - Uses the
mailparserlibrary to parse raw email data into structured format. - Requires appropriate n8n credential configuration for the IMAP server authentication.
Troubleshooting
- Connection errors: Ensure IMAP server details and credentials are correct. Verify network connectivity and firewall rules.
- Authentication failures: Check username and password; some servers require app-specific passwords or OAuth tokens.
- Empty results: Confirm mailbox name is correct and filters are not too restrictive (e.g., date range or subject filter).
- Attachment inclusion issues: If attachments are not appearing, verify the "Include Attachments" option is enabled and emails actually contain attachments.
- Timeouts or slow responses: Large mailboxes or high limits may cause delays; try reducing the limit or narrowing filters.
- Error messages: Errors thrown during fetching or parsing will be reported. Use "Continue On Fail" to handle partial failures gracefully.