Cordova IMAP plugin

This plugin will enable a Cordova application to use the IMAP (Internet Message Access Protocol) features. The plugin offers support for Android and iOS. To enable the IMAP features on Android, this plugin uses the framework Java Mail API and for iOS, it uses the MailCore 2 library.

Supported Platforms

• Android
• iOS

Installation

Install the plugin by running:

cordova plugin add cordova-plugin-imap

How to install on Ionic

More info for installation on Ionic including import examples on: Awesome Cordova Plugins

Cordova

# NOTE: Install Core library (once per project)
npm install @awesome-cordova-plugins/core

# Install the IMAP plugin
ionic cordova plugin add cordova-plugin-imap

# Install the Awesome Cordova Plugins TypeScript wrapper
npm install @awesome-cordova-plugins/imap

Capacitor

# NOTE: Install Core library (once per project)
npm install @awesome-cordova-plugins/core

# Install the IMAP plugin
npm install cordova-plugin-imap

# Install the Awesome Cordova Plugins TypeScript wrapper
npm install @awesome-cordova-plugins/imap

# Update native platform project(s) to include newly added plugin
ionic cap sync

API

• connect(config, success, error) - (Connection) - Tries to connect and authenticate with the IMAP server.
• disconnect(success, error) - (boolean) - Closes the connection with the server.
• isConnected(success, error) - (boolean) - Checks the current state of the connection.
• listMailFolders(pattern, success, error) - (string[]) - Lists the name of all the mail folders in the mailbox.
• getMessageCountByFolderName(folderName, success, error) - (number) - Gets the count of the messages in the folder.
• searchMessagesByDatePeriod(folderName, dateInMilliseconds, comparison : enum, success, error) - (number[]) - Returns the messages' consecutive numbers.
• listMessagesHeadersByConsecutiveNumber(folderName, start, end, success, error) - (MessageHeaders[]) - Returns messages' headers data.
• listMessagesHeadersByDate(folderName, dateInMilliseconds, comparison : enum, success, error) - (MessageHeaders[]) - Returns messages' headers data.
• getFullMessageData(folderName, messageNumber, success, error) - (Message) - Returns the full message data inclucing its attachments.
• getFullMessageDataOnNewSession(config, folderName, messageNumber, success, error) - (Message) - Returns the full message data inclucing its attachments.
• copyToFolder (sourceFolder, destinationFolder, messageNums, success, error) - (boolean) - Copy messages to a desired folder
• setFlag (folderName, messageNums, flag : enum, status, success, error) - (ModificationResult) - Sets a flag on a message. This method can also be used for deleting messages.

Data types

Config

| Param | Type | Description | | --- | --- | --- | | host | string | Hostname or IP address of the IMAP service. | | port | number | Optional. Port of the IMAP server to connect. Default set to: 993 | | connectionType | ConnectionType | iOS ONLY. Optional. Encryption type to use. Default set to: TLS/SSL | | user | string | Username or email address for authentication. | | password | string | Password for authentication. |

ConnectionType enum

| Name | Type | Description | | --- | --- | --- | | Clear | MCOConnectionType | Clear-text connection for the protocol. | | StartTLS | MCOConnectionType | Start with clear-text connection at the beginning, then switch to encrypted connection using TLS/SSL | | TLS/SSL | MCOConnectionType | Encrypted connection using TLS/SSL |

Connection

| Param | Type | Description | | --- | --- | --- | | status | boolean | Connection status. | | connection | string | Optional. Connection String result, returned when the connection is established successfully. | | exception | string | Optional. Exception details, in case an error occurs. |

MessageHeaders

| Param | Type | Description | | --- | --- | --- | | messageNumber | number | Message consecutive number. | | folder | string | The name of the message's folder. | | from | Array<Address> | Sender's data. | | toRecipients | Array<Address> | TO recipients data. | | ccRecipients | Array<Address> | CC recipients data. | | bccRecipients | Array<Address> | BCC recipients data. | | receivedDate | string | The date when the message was received. | | subject | string | Message's subject. | | flags | Array<string> | Message's active flags |

Message

| Param | Type | Description | | --- | --- | --- | | messageNumber | number | Message consecutive number. | | folder | string | The name of the message's folder. | | from | Array<Address> | Sender's data. | | allRecipients | Array<Address> | All recipients data. | | toRecipients | Array<Address> | TO recipients data. | | ccRecipients | Array<Address> | CC recipients data. | | bccRecipients | Array<Address> | BCC recipients data. | | replyTo | Array<Address> | Reply data. | | sentDate | string | The date when the message was sent. | | receivedDate | string | The date when the message was received. | | subject | string | Message's subject. | | description | string | Android ONLY. Optional. Short description. | | fileName | string | / | | disposition | string | Android ONLY. Optional. / | | flags | Array<string> | Message's active flags | | lineCount | number | Android ONLY. Optional. / | | allMessageHeaders | object | Android ONLY. Optional. All Headers available on a message | | contentType | string | Android ONLY. Optional. Type of message's content | | bodyContent | Array<Content> | Message's body with its content and attachments. | | size | number | Message's memory size |

Address

| Param | Type | Description | | --- | --- | --- | | address | string | Email address | | personal | string | Optional. Name of the email address's owner. | | type | string | Android ONLY. Optional. Data type |

Content

| Param | Type | Description | | --- | --- | --- | | type | string | Content data type | | fileName | string | Optional. The name of the file | | content | string | Message's content |

ModificationResult

| Param | Type | Description | | --- | --- | --- | | status | boolean | Status of the applied changes | | modifiedMessages | Array<number> | Array with consecutive numbers of modified messages |

Flag : enum

Defines a flag that can be added or removed from a message.

Note: Some flags are available only for a particular platform

Kind: static enum property of flag
Available Flags

| Name | Type | Description | | --- | --- | --- | | ANSWERED | Flags.Flag / MCOMessageFlag | "ANSWERED" message flag | | DRAFT | Flags.Flag / MCOMessageFlag | "DRAFT" message flag | | FLAGGED | Flags.Flag / MCOMessageFlag | "FLAGGED" message flag | | RECENT | Flags.Flag | Android ONLY. "RECENT" message flag | | SEEN | Flags.Flag / MCOMessageFlag | "SEEN" message flag | | USER | Flags.Flag | Android ONLY. "USER" message flag | | DELETED | Flags.Flag / MCOMessageFlag | "DELETED" message flag. Note: Add this flag to delete the message from the mailbox | | SENT | MCOMessageFlag | iOS ONLY. "SENT" message flag | | FORWARDED | MCOMessageFlag | iOS ONLY. "FORWARDED" message flag | | SubmitPending | MCOMessageFlag | iOS ONLY. "SubmitPending" message flag | | SUBMITTED | MCOMessageFlag | iOS ONLY. "SUBMITTED" message flag |

ComparisonTerm : enum

Comparison Operators. Used for listing messages by date period.

Note: Some operators are available only for a particular platform

Kind: static enum property of comparison
Available Operators

| Name | Type | Description | | --- | --- | --- | | LE | ReceivedDateTerm | Android ONLY. The less than or equal to operator. | | LT | ReceivedDateTerm / MCOIMAPSearchExpression | The less than operator. | | EQ | ReceivedDateTerm / MCOIMAPSearchExpression | The equality operator. | | NE | ReceivedDateTerm / MCOIMAPSearchExpression | The not equal to operator. | | GT | ReceivedDateTerm | Android ONLY. The greater than operator. | | GE | ReceivedDateTerm / MCOIMAPSearchExpression | The greater than or equal to operator. |

License

ISC

Thank you

Thank you for using this plugin. If you have any suggestions on how we can improve the plugin (missing feature or bug...), feel free to contact us.