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.

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

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

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

Data Sources

List Mailboxes

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

Input	Notes
Connection connection / Required connection

Actions

Add Flags

Add new flags to an existing message | key: addFlags

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

Append Message

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

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

Copy Message

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

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

Example Payload for Copy Message

{
  "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

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

Delete Message

Delete an existing message | key: deleteMessage

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

Example Payload for Delete Message

{
  "data": true
}

Download Message

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

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

Get Mailbox Status

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

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

Example Payload for Get Mailbox Status

{
  "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

Input	Notes
Connection connection / Required connection

Example Payload for List Mailboxes

{
  "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

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

Rename Mailbox

Change the name of an existing mailbox | key: renameMailbox

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

Search / List Mailbox Messages

Returns all messages in the given mailbox | key: searchMailbox

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

Set Flags

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

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

Interact with your IMAP email account

Description​

Connections​

IMAP Connection​

Connecting to Gmail​

Connecting to Microsoft Office 365​

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​

Description

Connections

IMAP Connection

Connecting to Gmail

Connecting to Microsoft Office 365

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