cordova-plugin-imap

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 including 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.
• downloadEmailAttachment(folderName, messageNo, path, replaceIfDuplicate, fileName, contentID, success, error) - Download email attachment using "fileName" or "contentID" – Android only. "contentID" is preferred when available, and it works only on Android.

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, if the message content is a file attachment
contentID	string	Android ONLY. Optional. "contentID" is a unique identifier for the attachment, used to fetch the file. It is preferred over "fileName" when available
content	string	Optional. 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 I can improve the plugin (missing features, bugs, etc.), feel free to contact me.