Skip to main content

IMAP Component

Interact with your IMAP email account

Component key: imap

Description#

IMAP or 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 allows you to interact with mailboxes and messages on any IMAP server.

Further information can be found in the underlying Node library's documentation.

IMAP Connections#

IMAP Connection#

To configure a connection to an IMAP server you will need a few properties:

  • The host and port of your IMAP server
  • A set of login credentials for a user that exists on the IMAP server
  • The version of encryption the IMAP server is compatible with.

The setup can vary widely depending on the email service you are using. We have provided a bit of context around some popular services to get you started.

Connecting to Gmail#

To set up an IMAP connection to your Gmail account, you need to create a Google App Password. Go to your Google Account and select 'Security'. Under "Signing in to Google," select App Passwords. You may need to sign in.

If you don't have this option, it might be because:

  • 2 Step Verification is not set up for your account.
  • 2 Step Verification is only set up for security keys.
  • Your account is through work, school, or other organization.
  • You turned on Advanced Protection.

At the bottom, click Select App and choose Mail, and then click Select device and choose Other (Custom name). Then, click GENERATE. You'll be given a 16-character code, which is your app password. Copy that somewhere safe.

Finally, create a connection in Prismatic and provide these values:

  • Enter imap.gmail.com for the host
  • The default values for port and security are fine
  • Enter the username or email of your Gmail account
  • Enter the app password you created earlier

If you run into authentication problems, ensure that your account has IMAP enabled.

Connecting to Microsoft Office 365#

If your Office 365 domain does not use multi-factor authentication (this is rare), then you can use your username and password to authenticate.

If MFA is enabled, you will need to create an app password 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.

If you don't have an app password option, you'll need to contact your Office 365 administrator and have them enable it.

Give your app password a name, and copy the password that is generated.

Now, create a connection in Prismatic and provide these values:

  • Enter outlook.office365.com for the host
  • The default values for port and security are fine
  • Enter the username or email of your Outlook account
  • Enter your password or the app password you generated
InputDefaultNotesExample
Input
Host
string
/ Required
Default
Notes
Provide the host address for the desired IMAP server.
Example
imap.example.com
Input
Maximum TLS Version
string
/ Required
Default
TLSv1.3
Notes
Provide a valid TLS version to be used in the connection.
Example
TLSv1.3
Input
Min DH Size
string
/ Required
Default
1024
Notes
Minimum size of bits to accept in a TLS connection
Example
512
Input
Minimum TLS Version
string
/ Required
Default
TLSv1.1
Notes
Provide a valid TLS version to be used in the connection.
Example
TLSv1.1
Input
Password
password
Default
Notes
Provide the password for the given user. This value is required if secured is set to true.
Example
examplePassword
Input
Port
string
/ Required
Default
993
Notes
Provide the port for the desired IMAP server.
Example
993
Input
Secure
boolean
/ Required
Default
Notes
Determines if the connection is secure.
Example
 
Input
Username
string
/ Required
Default
Notes
Provide a valid username or email.
Example
someone@example.com

Data Sources#

List Mailboxes#

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

InputNotes
Input
Connection
connection
/ Required
Notes
 

Actions#

Add Flags#

Add new flags to an existing message | key: addFlags

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

Append Message#

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

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Message Content
string
/ Required
Notes
Mailbox path to upload the message to
Example
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.
Input
Mailbox
string
/ Required
Notes
Provide a string value for the name of the mailbox
Example
INBOX
Input
Path
string
/ Required
Notes
Mailbox path to upload the message to
Example
INBOX

Copy Message#

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

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

Output Example Payload#

{  "data": {    "path": "My-Source-Mailbox",    "destination": "My-Destination-Mailbox",    "uidValidity": "596391920",    "uidMap": []  }}

Create Mailbox#

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

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Path
string
/ Required
Notes
Mailbox path to upload the message to
Example
INBOX

Delete Message#

Delete an existing message | key: deleteMessage

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Mailbox
string
/ Required
Notes
Provide a string value for the name of the mailbox
Example
INBOX
Input
Message UID
string
Notes
The UID of the message.
Example
5

Output Example Payload#

{  "data": true}

Download Message#

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

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Mailbox
string
/ Required
Notes
Provide a string value for the name of the mailbox
Example
INBOX
Input
Message Index or ID
string
Notes
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.
Example
5

Get Mailbox Status#

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

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
Mailbox
string
/ Required
Notes
Provide a string value for the name of the mailbox
Example
INBOX

Output Example Payload#

{  "data": {    "path": "INBOX",    "highestModseq": "10914782",    "messages": 61,    "recent": 0,    "uidNext": 76791,    "uidValidity": "596391842",    "unseen": 41  }}

List Mailboxes#

Returns a list of available mailboxes | key: listMailboxes

InputNotes
Input
Connection
connection
/ Required
Notes
 

Output Example Payload#

{  "data": [    {      "path": "Drafts",      "pathAsListed": "Drafts",      "flags": {},      "delimiter": "/",      "listed": true,      "parentPath": "",      "parent": [],      "name": "Drafts",      "subscribed": true    },    {      "path": "INBOX",      "pathAsListed": "INBOX",      "flags": {},      "delimiter": "/",      "listed": true,      "specialUse": "\\Inbox",      "parentPath": "",      "parent": [],      "name": "INBOX",      "subscribed": true    },    {      "path": "Sent",      "pathAsListed": "Sent",      "flags": {},      "delimiter": "/",      "listed": true,      "parentPath": "",      "parent": [],      "name": "Sent",      "subscribed": true    }  ]}

Remove Flags From Message#

Remove existing flags from an existing message | key: removeFlags

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

Rename Mailbox#

Change the name of an existing mailbox | key: renameMailbox

InputNotesExample
Input
Connection
connection
/ Required
Notes
 
Example
 
Input
New Path
string
/ Required
Notes
Mailbox path to upload the message to
Example
INBOX
Input
Path
string
/ Required
Notes
Mailbox path to upload the message to
Example
INBOX

Search / List Mailbox Messages#

Returns all messages in the given mailbox | key: searchMailbox

InputDefaultNotesExample
Input
Connection
connection
/ Required
Default
 
Notes
 
Example
 
Input
From
string
Default
Notes
Filter email messages by sender
Example
someone@example.com
Input
Mailbox
string
/ Required
Default
Notes
Provide a string value for the name of the mailbox
Example
INBOX
Input
Read / Unread Filter
string
/ Required
Default
all
Notes
 
Example
 
Input
To
string
Default
Notes
Filter email messages by recipient
Example
someone@example.com

Set Flags#

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

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