IMAP Connector

Description

IMAP (Internet Message Access Protocol) is an Internet standard protocol used by email clients to retrieve email messages from a mail server over a TCP/IP connection. This component gives you the ability to list mailboxes, search and fetch emails, manage message flags, and copy or move messages on any IMAP server.

API Documentation

This component was built using the ImapFlow Node.js library.

Connections

IMAP Connection

key: imap

To configure a connection to an IMAP server, the server's host address, port, login credentials, and TLS settings are required.

The setup can vary widely depending on the email service in use. Context for some popular services is provided below.

Prerequisites

Access to an IMAP-enabled email account
The IMAP server host address and port
Valid login credentials (username and password or app password)

Setup Steps

Gmail

To set up an IMAP connection to a Gmail account, create a Google App Password:

Navigate to the Google Account page and select Security.
Under Signing in to Google, select App Passwords. Sign-in may be required.
If the App Passwords option is not available, possible reasons include:
- 2-Step Verification is not set up for the account
- 2-Step Verification is only set up for security keys
- The account is through work, school, or another organization
- Advanced Protection is enabled
At the bottom, click Select App and choose Mail, then click Select device and choose Other (Custom name).
Click GENERATE.
A 16-character code will be generated — this is the app password. Copy it to a safe location.

If authentication problems occur, ensure the account has IMAP enabled.

Microsoft Office 365

If the Office 365 domain does not use multi-factor authentication (this is rare), the username and password can be used to authenticate directly.

If MFA is enabled, an app password is required to authenticate. To create an app password:

Log in to the Microsoft Security Center and open the Security info tab.
Click +Add method and choose App password.
Enter a name for the app password, and copy the password that is generated.

If the App password option is unavailable, contact the Office 365 administrator to enable it.

Configure the Connection

Create a connection of type IMAP Connection and enter the following values:

Input	Description	Default
Host	The IMAP server hostname (e.g., `imap.gmail.com` for Gmail, `outlook.office365.com` for Office 365)	—
Port	The IMAP server port	`993`
Secure	Whether to use a secure (TLS) connection	`true`
Username	The email address or username for the IMAP account	—
Password	The account password or app password	—
Minimum TLS Version	The minimum TLS version accepted by the connection	`TLSv1.1`
Maximum TLS Version	The maximum TLS version accepted by the connection	`TLSv1.3`
Min DH Size	Minimum key size (in bits) to accept in a TLS connection	`1024`

On-prem enabled: this connection can be configured to connect to an on-prem resource on a private network. Learn more.

Input	Notes	Example
Host	Provide the host address for the desired IMAP server.	imap.example.com
Maximum TLS Version	Provide a valid TLS version to be used in the connection.	TLSv1.3
Min DH Size	Minimum size of bits to accept in a TLS connection	512
Minimum TLS Version	Provide a valid TLS version to be used in the connection.	TLSv1.1
Password	Provide the password for the given user. This value is required if secured is set to true.	examplePassword
Port	Provide the port for the desired IMAP server.	993
Secure	Determines if the connection is secure.	true
Username	Provide a valid username or email.	someone@example.com

Triggers

New Emails

Retrieves existing and new emails for a specified IMAP mailbox. Load history once, check for changes on a schedule, or both. | key: newEmailsPollingTrigger

Input	Notes	Example
Connection	The IMAP connection to use.
Fetch Content	When enabled, downloads and parses the full message body for each new email.	false
Look-back Date	The date the initial sync starts from, in YYYY-MM-DD format. Cannot be a future date. Leave empty to start from the first recurrence with no backfill. When set, the initial sync delivers each email received on or after this date once.	2026-01-01
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Mark as Read	When enabled, sets the Seen flag on new emails after polling.	false

This trigger retrieves existing and new emails for a specified IMAP mailbox. Load history once, check for changes on a schedule, or both.

How It Works

On each scheduled recurrence, the trigger connects to the IMAP server and checks the mailbox status. It uses IMAP UIDs to track which messages have already been processed, ensuring each email is returned only once.

On the first recurrence without a Look-back Date (or when uidValidity changes, indicating the mailbox was rebuilt), the trigger records the current UID state and emits nothing. Subsequent recurrences fetch messages with UIDs above the stored threshold.

When Fetch Content is enabled, the full email body and attachment metadata are included in the results. When Mark as Read is enabled, fetched messages are flagged as \Seen on the server.

Initial sync

An initial sync seeds a complete starting state from the mailbox. It begins on the first recurrence when the trigger has no stored UID position and a Look-back Date (YYYY-MM-DD) is set: an IMAP SEARCH SINCE finds the messages whose internal date is on or after that date, and the trigger fetches every message from the lowest matching UID onward, delivering each once. No input is ignored while it runs. A later uidValidity change starts a new sync from the same date, so a rebuilt mailbox can deliver messages again. Left empty, there is no sync and the trigger starts from its first recurrence.

The sync completes in one recurrence whether or not batching is on. Its fetch has no fixed upper bound, but the position the trigger stores is the mailbox's next UID as read at the start of that recurrence, so a message that arrives while the sync runs can be delivered again by the next recurrence. Later recurrences fetch from that stored UID onward. No field in the payload marks the handoff.

Mailbox, Fetch Content, and Mark as Read still apply. With Mark as Read on, every message the sync delivers is flagged \Seen, including older unread messages.

Batching

Batching is enabled per flow on this trigger: each email is dispatched as its own execution, or grouped by the configured batch size. Batch size and batch concurrency can both be overridden per instance. Raising concurrency increases the connection volume to the IMAP server.

To turn it on, select the flow's trigger, open the Flow control tab, and switch on Enable Batching. Under Batch Size, keep Trigger default or choose Custom batch size. Batch Concurrency is optional; leave it blank for no batch-level limit.

With batching off, downstream steps read results.body.data as an array of email objects. With batching on, each execution receives a single { changeType, record } item representing one email. Any step reading the older shape must be updated before batching is enabled. Because batching is enabled per flow, the change is scoped to that flow.

Returned Data

The trigger returns an array of email objects. Fields shown are representative. The full response object includes additional properties.

Example Response

[
  {
    "uid": 1066,
    "envelope": {
      "date": "2026-02-18T23:02:20.000Z",
      "subject": "Weekly Team Update",
      "from": [{ "name": "Jane Doe", "address": "jane@example.com" }],
      "sender": [{ "name": "Jane Doe", "address": "jane@example.com" }],
      "replyTo": [{ "name": "Jane Doe", "address": "jane@example.com" }],
      "to": [{ "name": "", "address": "inbox@example.com" }],
      "messageId": "<abc123-def456@mail.example.com>"
    },
    "flags": [],
    "internalDate": "2026-02-18T23:02:20.000Z",
    "size": 33932
  },
  {
    "uid": 1067,
    "envelope": {
      "date": "2026-02-19T16:20:01.000Z",
      "subject": "Your monthly report is ready",
      "from": [
        { "name": "Acme Reports", "address": "reports@acme.example.com" }
      ],
      "sender": [
        { "name": "Acme Reports", "address": "reports@acme.example.com" }
      ],
      "replyTo": [
        { "name": "Acme Reports", "address": "reports@acme.example.com" }
      ],
      "to": [{ "name": "", "address": "inbox@example.com" }],
      "messageId": "<ghi789-jkl012@mail.acme.example.com>"
    },
    "flags": ["\\Seen"],
    "internalDate": "2026-02-19T16:20:01.000Z",
    "size": 89372
  }
]

Batched Item Shape

When batching is enabled, each execution receives a single item:

{
  "changeType": "created",
  "record": {
    "uid": 1066,
    "envelope": {
      "date": "2026-02-18T23:02:20.000Z",
      "subject": "Weekly Team Update",
      "from": [{ "name": "Jane Doe", "address": "jane@example.com" }],
      "to": [{ "name": "", "address": "inbox@example.com" }]
    },
    "flags": [],
    "internalDate": "2026-02-18T23:02:20.000Z",
    "size": 33932
  }
}

Data Sources

List Mailboxes

Returns a picklist of available mailboxes that users can choose from | key: listMailboxes | type: picklist

Input	Notes	Example
Connection	The IMAP connection to use.

Actions

Add Flags

Add new flags to an existing message | key: addFlags

Input	Notes	Example
Connection	The IMAP connection to use.
Flags	For each item, provide a string value to be added to an existing message.	exampleFlag
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Range	Provide a range of messages. Alternatively you can specify * to get the latest message.	1,2,4:6

Example Payload for Add Flags⤓

Loading…

Append Message

Appends a new message to an existing mailbox | key: appendMessage

Input	Notes	Example
Connection	The IMAP connection to use.
Message Content	The raw RFC 822 formatted message content to append.	From: someone@<yourcompany>.com Subject: A basic RFC 850 formatted message Newsgroups: comp.<yourcompany>.test The body of this message is plain text. Note the blank line between the header information and the body of the message.
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Path	Mailbox path to upload the message to.	INBOX

Example Payload for Append Message⤓

Loading…

Copy Message

Copies a message from one mailbox to another. | key: copyMessage

Input	Notes	Example
Connection	The IMAP connection to use.
Mailbox	Provide a string value for the name of the mailbox.	INBOX
New Path	Mailbox path to upload the message to.	INBOX
Range	Provide a range of messages. Alternatively you can specify * to get the latest message.	1,2,4:6

Example Payload for Copy Message⤓

Loading…

Create Mailbox

Creates a new mailbox folder and sets up subscription for the created mailbox | key: createMailbox

Input	Notes	Example
Connection	The IMAP connection to use.
Path	Mailbox path to upload the message to.	INBOX

Example Payload for Create Mailbox⤓

Loading…

Delete Message

Delete an existing message | key: deleteMessage

Input	Notes	Example
Connection	The IMAP connection to use.
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Message UID	The UID of the message.	5

Example Payload for Delete Message⤓

Loading…

Download Message

Download either full RFC-822 formatted message or a specific body structure part | key: downloadMessage

Input	Notes	Example
Connection	The IMAP connection to use.
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Message Index or ID	The index of the message you would like to download (1 for the oldest message, 2 for second oldest, etc), or the ID of the message.	5

Example Payload for Download Message⤓

Loading…

Get Mailbox Status

Returns the status of a mailbox's properties | key: getStatus

Input	Notes	Example
Connection	The IMAP connection to use.
Mailbox	Provide a string value for the name of the mailbox.	INBOX

Example Payload for Get Mailbox Status⤓

Loading…

List Mailboxes

Returns a list of available mailboxes | key: listMailboxes

Input	Notes	Example
Connection	The IMAP connection to use.

Example Payload for List Mailboxes⤓

Loading…

Remove Flags From Message

Remove existing flags from an existing message | key: removeFlags

Input	Notes	Example
Connection	The IMAP connection to use.
Flags	For each item, provide a string value to be added to an existing message.	exampleFlag
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Range	Provide a range of messages. Alternatively you can specify * to get the latest message.	1,2,4:6

Example Payload for Remove Flags From Message⤓

Loading…

Rename Mailbox

Change the name of an existing mailbox | key: renameMailbox

Input	Notes	Example
Connection	The IMAP connection to use.
New Path	Mailbox path to upload the message to.	INBOX
Path	Mailbox path to upload the message to.	INBOX

Example Payload for Rename Mailbox⤓

Loading…

Search / List Mailbox Messages

Returns all messages in the given mailbox | key: searchMailbox

Input	Notes	Example
Connection	The IMAP connection to use.
Filter Options	Extra parameters to filter the search results.	`{ "recent": true, "subject": "example", "from": "someone@example.com", "to": "someone@example.com", "since": "2025-01-01", "before": "2025-01-01" }`
From	Filter email messages by sender.	someone@example.com
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Read / Unread Filter	Filter messages by read or unread status.	all
To	Filter email messages by recipient.	someone@example.com

Example Payload for Search / List Mailbox Messages⤓

Loading…

Set Flags

Set a value for an existing message flag | key: setFlags

Input	Notes	Example
Connection	The IMAP connection to use.
Flags	For each item, provide a string value to be added to an existing message.	exampleFlag
Mailbox	Provide a string value for the name of the mailbox.	INBOX
Range	Provide a range of messages. Alternatively you can specify * to get the latest message.	1,2,4:6

Example Payload for Set Flags⤓

Loading…

Changelog

2026-10-20

Added opt-in batching and an initial sync to the New Emails polling trigger:

Added opt-in batching to the New Emails trigger, dispatching each new email individually or in configured batches; enabling it changes the shape a downstream step receives
Added an optional Look-back Date input to the New Emails trigger for performing an initial sync of emails. The initial sync begins on the first recurrence and backfills every email received on or after the specified date, seeding each once; later recurrences are unaffected. Leave it empty to start from the first recurrence with no backfill

2026-04-30

Updated spectral version

2026-04-07

Added global debug support across all actions for improved troubleshooting

2026-02-18

Added New Emails polling trigger to fetch new emails from a specified mailbox on a recurring schedule

2025-07-21

Modified Download Message action for enhanced functionality and improved message handling
Added metadata fields to the Download Attachment action for better message processing capabilities
Modernized IMAP component and added more metadata fields to actions for improved email management and processing

IMAP Connector

Description​

API Documentation​

Connections​

IMAP Connection​

Prerequisites​

Setup Steps​

Gmail​

Microsoft Office 365​

Configure the Connection​

Triggers​

New Emails​

How It Works​

Returned Data​

Data Sources​

List Mailboxes​

Actions​

Add Flags​

Append Message​

Copy Message​

Create Mailbox​

Delete Message​

Download Message​

Get Mailbox Status​

List Mailboxes​

Remove Flags From Message​

Rename Mailbox​

Search / List Mailbox Messages​

Set Flags​

Changelog​

2026-10-20​

2026-04-30​

2026-04-07​

2026-02-18​

2025-07-21​

Description

API Documentation

Connections

IMAP Connection

Prerequisites

Setup Steps

Gmail

Microsoft Office 365

Configure the Connection

Triggers

New Emails

How It Works

Returned Data

Data Sources

List Mailboxes

Actions

Add Flags

Append Message

Copy Message

Create Mailbox

Delete Message

Download Message

Get Mailbox Status

List Mailboxes

Remove Flags From Message

Rename Mailbox

Search / List Mailbox Messages

Set Flags

Changelog

2026-10-20

2026-04-30

2026-04-07

2026-02-18

2025-07-21