Receiving and Processing Emails

The common process for receiving emails has the following steps:

1. Retrieve a set of messages from the server.

2. Process the returned set of messages.

3. Delete all or some messages, or move them to a specific folder.

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 ImplementationFor PGP decryption to work, be sure to register your implementation of IPgpKeyProvider (see (25.1) Keys and Certificates). If not provided, PGP encrypted messages will still be retrieved, with two attachments that contain the encrypted message information. ParameterTypeDirectionDescriptionconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).flags(25.1) JavaMail Library Reference#ReadFlagsinSpecify an instance of ReadFlags to set some mail reading flags.folderPathStringinSpecify a path to a folder to read from. See note regarding folder handling.

readMessagesFiltered

Optional: IPgpKeyProvider ImplementationFor PGP decryption to work, be sure to register your implementation of IPgpKeyProvider (see (25.1) Keys and Certificates). If not provided, PGP encrypted messages will still be retrieved, with two attachments that contain the encrypted message information. ParameterTypesDirectionDescriptionconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).flags(25.1) JavaMail Library Reference#ReadFlagsinSpecify an instance of ReadFlags (see below).folderPathStringinSpecify a path to a folder to read from. See note regarding folder handling.filter(25.1) JavaMail Library Reference#FilterinSpecify an instance of Filter containing the filter criteria.

Types

ReadFlags

Attribute NameTypeDescriptionAllowed ValuesCommentmaxResultCountIntegerSpecify a limit for the number of messages to be returned.If you do not provide a filter as parameter, it makes sense to provide a meaningful limit, as the complete result set will be kept in memory.any positive integerDefault is NULL, meaning no limit is imposed.deleteOnServerBooleanSpecify whether successfully read messages will automatically be deleted on the server.trueDelete messages on server after successful read. Messages that cannot be read successfully will not be deleted.falseDo not delete messages on server (default).markAsReadBooleanSpecify whether successfully read messages will automatically be marked as read on the server.trueMark messages as read on server after successful read. Messages that cannot be read successfully will not be marked read.falseDo not mark messages read on server (default).withContentBooleanSpecify whether the message body (HTML and/or plain text) should be populated.truePopulate message body.falseMessage body is empty (default).withAttachmentsBooleanSpecify whether attachments should be retrieved.trueRetrieve attachments.falseDo not retrieve attachments (default).withEmbeddedMailsBooleanSpecify whether attachments with mime type message/rfc822 should be retrieved as embedded messages. Requires withAttachments to be true to have an effect.trueRetrieve attachments with mime type message/rfc822 as embedded messages.falseDo not retrieve attachments with mime type message/rfc822 as embedded messages, but as regular attachments (default).withHeadersBooleanSpecify whether messaging headers should be populated.truePopulate messaging headers.falseMessaging headers are empty (default).withRawContentsBooleanSpecify whether the raw message source should be retrieved.trueRetrieve raw message source.This is similar to "view source" on most email clients, hence the output can be huge.falseDo not retrieve raw message source (default).verifySignaturesBooleanSpecify whether for any signed messages a verification of the signature should be attempted.trueVerify signature.To successfullly verify PGP signatures, a public key ring must be provided with the connection parameter.falseDo not verify signature (default).

Filter

Attribute NameTypeDescriptionAllowed ValuesunreadOnlyBooleanSpecify whether only unread messages should be returned.trueReturn unread messages only.falseReturn all messages (default).fromTimestampDateTimeSpecify the beginning of a date range that should be used to retrieve messages (see also toTimestamp below).Make sure that fromTimestamp and toTimestamp do not contradict each other as this is not checked.any DateTimetoTimestampDateTimeSpecify the end of a date range that should be used to retrieve messages (see also fromTimestamp below).Make sure that fromTimestamp and toTimestamp do not contradict each other as this is not checked.any DateTimesubjectSubstringStringSpecify a filter substring for the email subject. Only messages containing this string as a literal substring are returned.subjectSubstring is case sensitive.any String with printable characters (case sensitive)senderStringSpecify a dedicated sender you want to retrieve messages from. Only message sent from this address are returnedany valid email address (case insensitive)senderRegexStringSpecify 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)subjectRegexStringSpecify 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)attachmentNameRegexStringSpecify 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.Make sure that you are using withAttachments = true when reading the mails (see (25.1) JavaMail Library Reference#ReadFlags).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 NameTypeDescriptionPossible ValuessenderStringContains the email address of the sender.toRecipientsArray of StringContains an array of TO recipient's email addresses.ccRecipientsArray of StringContains an array of CC recipient's email addresses.bccRecipientsArray of StringContains an array of BCC recipient's email addresses.subjectStringContains the email subject.attachmentsArray of (25.1) JavaMail Library Reference#AttachmentContains an array of email attachments.If this is not populated, you may have set withAttachments = false when reading the mails (see (25.1) JavaMail Library Reference#ReadFlags).plainTextContentStringContains the plain text message if available.Mime messages may contain HTML, Plain Text, or both.htmlTextContentStringContains the HTML message if available.Mime messages may contain HTML, Plain Text, or both.idStringContains the unique ID of the message within a folder on the mail server.receiveDateDateTimeContains a timstamp indicating when the message arrived on the server.sentDateDateTimeContains a timstamp indicating when the message has been sent.headersArray of (25.1) JavaMail Library Reference#MailHeaderContains an array of internet email headers.If this is not populated, you may have set withHeaders = false when reading the mails (see (25.1) JavaMail Library Reference#ReadFlags).embeddedMailsArray of (25.1) JavaMail Library Reference#ReceivedMailContains an array of nested/embedded mail objects (attached email messages, e.g. .eml or .msg attachments).If this is not populated, you may have set withAttachments = false when reading the mails (see (25.1) JavaMail Library Reference#ReadFlags).receiveStatus(25.1) JavaMail Library Reference#MailReceiveStatusContains detailed information about the receive status of the email.folderStringContains the folder the message was read from.NULL<Inbox>.folder pathThe folder path below <Inbox>.signedBooleanContains the signing status of the message.trueMessage is signed.falseMessage is not signed.encryptedBooleanContains the encryption status of the message.detection is supported, however receiveStatus.success will always be false, as decryption is not yet supportedtrueMessage is encrypted.falseMessage is not encrypted.signatureVerificationResult(25.1) JavaMail Library Reference#SignatureVerificationResultContains detailed information about the verification of signatures.rawMessageTextBlobContains the raw message.If this is not populated, you may have set withRawContents = false when reading the mails (see (25.1) JavaMail Library Reference#ReadFlags).

Attachment

Attribute NameTypeDescriptionPossible ValuesbinaryBooleanIndicates whether binaryContent or stringContent is used.trueAttachment contents canl be found in, or shall be taken from, binaryContent.falseAttachment contents can/shall be found in, or shall be taken from, stringContent.filenameStringThe filename of the attachment.can be NULLSending MessagesThis is the name of the file as you want it to appear at the recipient's side, or vice versa.Do not provide a local file name here and expect the library to load the attachment from that file. Use the (25.1) File System Adapter instead, and provide the attachment as binary blob content (see binaryContent).binaryContentBlobContains the binary content.any BlobEither one of binaryContent or stringContent is provided, depending on binary.stringContentStringContains the non-binary content.any StringEither one of binaryContent or stringContent is provided, depending on binary.mimeTypeStringContains the mime type (content type) of the attachment.any valid MIME content-type, e.g. text/plain, image/png, application/octet-stream etc.mimeType is unreliable upon receiving emails, i.e. can be NULL. Especially when reading from Exchange servers using exchange or office365 connections.contentIdStringThe 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">inlineBooleanControls whether the attachment is flagged with the corresponding content disposition tag.trueAttachment is flagged, and will be displayed inline within a HTML message.falseAttachment 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.

deleteMessage

ParameterTypesDirectionDescriptionconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).mail(25.1) JavaMail Library Reference#ReceivedMailinProvide a previously received mail object.

deleteMessages

ParameterTypesDirectionDescriptionconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).mailArray of (25.1) JavaMail Library Reference#ReceivedMailinProvide an array previously received mail object.

deleteMessagesFiltered

ParameterTypesDirectionDescriptionAllowed Values / Exampleconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).folderPathStringinSpecify a path to a folder to delete from. See note regarding folder handling.orders/incomingfilter(25.1) JavaMail Library Reference#FilterinSpecify 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.affectedMessagesIntegeroutReturns 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 affectedMessages becomes 0.

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.

ParameterTypesDirectionDescriptionAllowed Values / Exampleconnection(25.1) JavaMail Library Reference#ConnectioninSpecify the Connection object defining the mail server connection parameters to use (see (25.1) Mail Server Connection).mail(25.1) JavaMail Library Reference#ReceivedMailinProvide an array previously received mail object.folderPathStringinSpecify a path to a specific sub-folder to move the message to. See note regarding folder handling.POP3 connections will cause an exception to be thrown here, as POP3 does not support the concept of folders.orders/incoming/accepted