Receiving and Processing Emails
The common process for receiving emails has the following steps:
- Retrieve a set of messages from the server.
- Process the returned set of messages.
- Delete all or some messages, or move them to a specific folder.
Operations expecting a folderPath argument will treat this the following way:
Folder Path | Description | Example |
---|---|---|
NULL | This is interpreted as meaning the | |
path beginning with / | This is interpreted as a path from the mail connections root folder. | /Archive/Orders |
path not beginning with / | This is interpreted as a relative path to the | Archive/Orders |
The intention of this behavior is to abstract away the fact that <Inbox>
has many different names depending on the connection, i.e. IMAP typically uses INBOX
, Exchange calls it Inbox
, and a German Exchange calls it Posteingang
.
Also note that POP3 does not support folders other than <Inbox>
. Hence when you specify a POP3 connection, folderPath parameters other than NULL will raise an exception.
Step 1: Retrieving Messages
You can retrieve messages using one of
- readMessages
- readMessagesFiltered
Both return an Array of ReceivedMail (see Processing Messages further below).
Operations
readMessages
Optional: IPgpKeyProvider Implementation
For PGP decryption to work, be sure to register your implementation of IPgpKeyProvider (see Keys and Certificates). If not provided, PGP encrypted messages will still be retrieved, with two attachments that contain the encrypted message information.
Parameter | Type | Direction | Description |
---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). |
flags | (24.3) JavaMail Library Reference#ReadFlags | in | Specify an instance of ReadFlags to set some mail reading flags. |
folderPath | String | in | Specify a path to a folder to read from. See note regarding folder handling. |
readMessagesFiltered
Optional: IPgpKeyProvider Implementation
For PGP decryption to work, be sure to register your implementation of IPgpKeyProvider (see Keys and Certificates). If not provided, PGP encrypted messages will still be retrieved, with two attachments that contain the encrypted message information.
Parameter | Types | Direction | Description |
---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). |
flags | (24.3) JavaMail Library Reference#ReadFlags | in | Specify an instance of ReadFlags (see below). |
folderPath | String | in | Specify a path to a folder to read from. See note regarding folder handling. |
filter | (24.3) JavaMail Library Reference#Filter | in | Specify an instance of Filter containing the filter criteria. |
Types
ReadFlags
Attribute Name | Type | Description | Allowed Values | Comment |
---|---|---|---|---|
maxResultCount | Integer | Specify a limit for the number of messages to be returned. | any positive integer | Default is NULL, meaning no limit is imposed. |
deleteOnServer | Boolean | Specify whether successfully read messages will automatically be deleted on the server. | true | Delete messages on server after successful read. Messages that cannot be read successfully will not be deleted. |
false | Do not delete messages on server (default). | |||
markAsRead | Boolean | Specify whether successfully read messages will automatically be marked as read on the server. | true | Mark messages as read on server after successful read. Messages that cannot be read successfully will not be marked read. |
false | Do not mark messages read on server (default). | |||
withContent | Boolean | Specify whether the message body (HTML and/or plain text) should be populated. | true | Populate message body. |
false | Message body is empty (default). | |||
withAttachments | Boolean | Specify whether attachments should be retrieved. | true | Retrieve attachments. |
false | Do not retrieve attachments (default). | |||
withEmbeddedMails | Boolean | Specify whether attachments with mime type message/rfc822 should be retrieved as embedded messages. Requires withAttachments to be true to have an effect. | true | Retrieve attachments with mime type message/rfc822 as embedded messages. |
false | Do not retrieve attachments with mime type message/rfc822 as embedded messages, but as regular attachments (default). | |||
withHeaders | Boolean | Specify whether messaging headers should be populated. | true | Populate messaging headers. |
false | Messaging headers are empty (default). | |||
withRawContents | Boolean | Specify whether the raw message source should be retrieved. | true | Retrieve raw message source. |
false | Do not retrieve raw message source (default). | |||
verifySignatures | Boolean | Specify whether for any signed messages a verification of the signature should be attempted. | true | Verify signature. |
false | Do not verify signature (default). |
Filter
Attribute Name | Type | Description | Allowed Values | |
---|---|---|---|---|
unreadOnly | Boolean | Specify whether only unread messages should be returned. | true | Return unread messages only. |
false | Return all messages (default). | |||
fromTimestamp | DateTime | Specify the beginning of a date range that should be used to retrieve messages (see also toTimestamp below). | any DateTime | |
toTimestamp | DateTime | Specify the end of a date range that should be used to retrieve messages (see also fromTimestamp below). | any DateTime | |
subjectSubstring | String | Specify a filter substring for the email subject. Only messages containing this string as a literal substring are returned. | any String with printable characters (case sensitive) | |
sender | String | Specify a dedicated sender you want to retrieve messages from. Only message sent from this address are returned | any valid email address (case insensitive) | |
senderRegex | String | Specify a regex filter to be applied to the mail sender. Only messages with the sender matching the filter expression are returned. | any valid regular expression (Java style) | |
subjectRegex | String | Specify a regex filter to be applied to the mail subject. Only messages with the subject matching the filter expression are returned. | any valid regular expression (Java style) | |
attachmentNameRegex | String | Specify a regex filter to be applied to the mail attachments. Only messages with at least one attachment's name matching the filter expression are returned. | any valid regular expression (Java style) |
Step 2: Processing Messages
You can process emails as you need. Retrieved messages are delivered as an Array of ReceivedMail objects, which inherit from Mail and add some more attributes available after receiving:
Classes
ReceivedMail
Attribute Name | Type | Description | Possible Values | |
---|---|---|---|---|
sender | String | Contains the email address of the sender. | ||
toRecipients | Array of String | Contains an array of TO recipient's email addresses. | ||
ccRecipients | Array of String | Contains an array of CC recipient's email addresses. | ||
bccRecipients | Array of String | Contains an array of BCC recipient's email addresses. | ||
subject | String | Contains the email subject. | ||
attachments | Array of (24.3) JavaMail Library Reference#Attachment | Contains an array of email attachments. | ||
plainTextContent | String | Contains the plain text message if available. | ||
htmlTextContent | String | Contains the HTML message if available. | ||
id | String | Contains the unique ID of the message within a folder on the mail server. | ||
receiveDate | DateTime | Contains a timstamp indicating when the message arrived on the server. | ||
sentDate | DateTime | Contains a timstamp indicating when the message has been sent. | ||
headers | Array of (24.3) JavaMail Library Reference#MailHeader | Contains an array of internet email headers. | ||
embeddedMails | Array of (24.3) JavaMail Library Reference#ReceivedMail | Contains an array of nested/embedded mail objects (attached email messages, e.g. .eml or .msg attachments). | ||
receiveStatus | (24.3) JavaMail Library Reference#MailReceiveStatus | Contains detailed information about the receive status of the email. | ||
folder | String | Contains the folder the message was read from. | NULL | <Inbox> . |
folder path | The folder path below <Inbox> . | |||
signed | Boolean | Contains the signing status of the message. | true | Message is signed. |
false | Message is not signed. | |||
encrypted | Boolean | Contains the encryption status of the message. detection is supported, however receiveStatus.success will always be false, as decryption is not yet supported | true | Message is encrypted. |
false | Message is not encrypted. | |||
signatureVerificationResult | (24.3) JavaMail Library Reference#SignatureVerificationResult | Contains detailed information about the verification of signatures. | ||
rawMessageText | Blob | Contains the raw message. |
Attachment
Attribute Name | Type | Description | Possible Values | |
---|---|---|---|---|
binary | Boolean | Indicates whether binaryContent or stringContent is used. | true | Attachment contents canl be found in, or shall be taken from, binaryContent. |
false | Attachment contents can/shall be found in, or shall be taken from, stringContent. | |||
filename | String | The filename of the attachment. |
| |
binaryContent | Blob | Contains the binary content. | any Blob | |
stringContent | String | Contains the non-binary content. | any String | |
mimeType | String | Contains the mime type (content type) of the attachment. | any valid MIME content-type, e.g. mimeType is unreliable upon receiving emails, i.e. can be NULL. Especially when reading from Exchange servers using exchange or office365 connections. | |
contentId | String | The content id of the attachment, a unique id across all attachments of the same message. | When set to e.g. myUniqueId, you can refer to this attachment from HTML message content like <img src="cid:myUniqueId"> | |
inline | Boolean | Controls whether the attachment is flagged with the corresponding content disposition tag. | true | Attachment is flagged, and will be displayed inline within a HTML message. |
false | Attachment is not flagged. |
Step 3: Deleting/Moving Messages
After messages have been retrieved, they are often deleted or moved to a specific folder.
Deleting Messages
Deleting messages is done by any one of the following operations:
- deleteMessage
- deleteMessages
- deleteMessagesFiltered
deleteMessage and deleteMessages operate on an instance of ReceivedMail, means you can call them on objects returned by a read on the mailbox. deleteMessagesFiltered operates on a folder and a filter criterion. It deletes all matching messages.
Deletion is always "hard" deletion. Mail items are not moved to "Trash" or "Deleted Items". Once deleted, the message is gone.
deleteMessage
Parameter | Types | Direction | Description |
---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). |
in | Provide a previously received mail object. |
deleteMessages
Parameter | Types | Direction | Description |
---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). |
in | Provide an array previously received mail object. |
deleteMessagesFiltered
Parameter | Types | Direction | Description | Allowed Values / Example |
---|---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). | |
folderPath | String | in | Specify a path to a folder to delete from. See note regarding folder handling. |
|
filter | (24.3) JavaMail Library Reference#Filter | in | Specify an instance of Filter containing the filter criteria. If no filter criteria are set, i.e. if you provide an empty filter, all messages will be deleted. | |
affectedMessages | Integer | out | Returns the number of deleted messages. | This might be lower than the total number of messages matching the filter if that number is huge, as mail servers may restrict the maximum number of messages processed in one call. If you want to be sure that all messages matching the filter are actually deleted, call this operation in a loop until |
Moving Messages
Moving messages operates in instances of ReceivedMail, objects returned by a read on the mailbox. You can specify the target folder to move the message to.
Parameter | Types | Direction | Description | Allowed Values / Example |
---|---|---|---|---|
connection | (24.3) JavaMail Library Reference#Connection | in | Specify the Connection object defining the mail server connection parameters to use (see Mail Server Connection). | |
(24.3) JavaMail Library Reference#ReceivedMail | in | Provide an array previously received mail object. | ||
folderPath | String | in | Specify a path to a specific sub-folder to move the message to. See note regarding folder handling. |
|
Related Pages: