POP3 component is used to connect to an mail server and retrieve emails using POP3 or IMAP protocol. It uses the JavaMail API.
The component supports two functions:
Retrieve emails from the mail server.
Fetch the email count on the mail server.
The following properties can be configured in the Managed Connection Properties panel of CPS.
Figure 1: Managed Connection Panel of POP3
Is POP3?
Specifies the protocol used to retrieve emails.
Yes – POP3 protocol is used to retrieve emails. The property Folder to pick mails is not visible if this value is selected.
No – IMAP protocol is used to retrieve emails. The property Folder to pick mails is visible if this value is selected.
MailserverURL
Specifies URL at which the mail server is hosted.
MailServer Port
Specifies port number on which the mail server accepts POP3 or IMAP connections.
UserID
User ID or Login name used to connect to the mail server. The user must have an email account with the server specified by the property MailserverURL.
Password
Password for the user specified by the property UserID.
Folder to pick mails
Specifies folder name from which emails are retrieved. This option is displayed only when the property Is POP3? is set to no.
Connection Timeout in ms
The duration in milliseconds for which the component waits to connect to the mail server (Socket connection timeout value in milliseconds). If the component fails to create a connection in the specified interval, then the retry behavior will depend on the configuration of Error Configuration Panel.
Timeout in ms
Socket I/O timeout value in milliseconds. If any operation requires more than the specified time then the operation will fail.
Server connection can be tested from within the CPS by clicking the Test button in the Connection Properties panel.
POP3 supports various options to retrieve mails from the server. The way the component interacts with the server can be configured in the Interaction Configurations panel.
Figure 2: Interaction Configuration panel
Operation Name
The operation that should be done after connecting to the server is specified here.
recvMail - retrieves and displays all the content in the email. If this operation is selected, the following properties are visible – Write attachments to file?, Enforce Text?, Enforce html?, Max message size, Max output size, Leave messages on server?, Send empty message when no other mails are present, Send XML output?
mailCount - retrieves the total number of mails in the account specified. If this operation is selected, the following properties are not visible – Write attachments to file?, Enforce Text?, Enforce html?, Max message size, Max output size, Leave messages on server?, Send empty message when no other mails are present, Send XML output?
Write attachments to file?
Specifies whether the attachments in the mail are to be written to a file.
yes – Attachments in retrieved email are written to files in the folder configured for property Attachments folder. Property Attachments folder is visible when this option is selected. savedToFile attribute of Attachment element in the output message is set to yes and the file name is added as content for Attachment element.
no – Each attachment in retrieved email is converted to a base64 encoded string and added as content for Attachment element in output XML. Property Attachments folder is not visible when this option is selected. savedToFile attribute of Attachment element in the output message is set to no.
Attachments folder
Specifies the path of the folder where attachments are saved. This property is visible only when the property Write attachments to file? is set to yes. The folder should exist in the machine on which the component is running.
If the attachment in the mail was loaded from a file, then the same file name is used to save attachment to the attachments folder.
If the attachment in the mail was not loaded from a file and the attachment contains a description, then the description text is used a file name to save attachment to the attachments folder.
If both the conditions are not met or the attachments folder is not present in the system or if there is any file system dependent error while saving , the attachment is not saved and resource warning is raised. For more information on resource warning, please refer to section Error Handling.
If the folder already contains a file with same name that is written by this component using the same connection that processed the current request then the file name is appended with time-stamp, else the file is over written.
Note: The folder path provided is not validated in the CPS..
Enforce Text?
This option is used when the property Send XML output? is set to yes and the email does not contain any text content. When this option is set to yes, html content in the email is converted to simple text. This property is visible only if property Send XML output? is set to yes.
Example: Each <BR> element is replaced with a new line character.
Enforce html?
This option is used when the property Send XML output? is set to yes and the email does not contain any html content. When this option is set to yes, text content in the email is converted to HTML. This property is visible only if property Send XML output? is set to yes.
Example: If the mail does not contain html content and the property Enforce html? Is set to no then the output message XML does not contains element HtmlBody as shown in Figure 3.
Figure 3: Output message of retrieval of a mail which has no html body when Enforce Html? is set to no
When Enforce html? Is set to yes, then the existing text body will be converted to html and it will be included in output XML as HtmlBody. The behavior is depicted in Figure 4. New line characters (/n or 
) in text content are converted to break line symbols (<BR>) in html content.
Figure 4: Output message of retrieval of a mail which has no html body when Enforce Html? is set to yes
Max message size
Specifies the maximum size limit on an email that is sent in the output. E-mails whose size is larger than the value specified for this property is not sent.
Max output size
Specifies the maximum limit on the combined size of emails that are included in the output message. Since more than one email can be retrieved in a message, this option allows control on the total size of all mails that may be returned in a single response.
Note: If the property Single Batch Mode set to No and Batch Count set to 1, then the properties Max Message size and Max output size will behave similarly.
Example: If mail server contains 10 mails each of size 10Kb and the property Max output size set to 30kb then, if the component receives a request to retrieve all the 10 mails then the component sends four messages to the output port.
First message --- contains first, second and third mails
Second message --- contains fourth, fifth and sixth mails
Third message --- contains seventh, eighth and ninth mails
Fourth message --- contains tenth mail
Leave Messages on Server
Specifies if the emails retrieved by this component are removed from the mail server or not.
yes – The emails retrieved are not deleted from the mail server and can be seen and fetched using other email clients.
no – The emails retrieved are deleted from the mail server as soon as the email is retrieved by the component.
Caution:
If connection pooling is not enabled and this property is set to yes, then emails are repeatedly retrieved with each request as the mails are not deleted from the mail server.
If connection pooling is enabled and the component is running in multi-threaded mode, then each thread will retrieve all the mails.
If connection pooling is enabled and a connection error happens, then all the mails are retrieved again when a new connection is made.
Send Empty message when no mails are present
If this property is set to yes, then an empty message is sent out for each request when there are no mails on the mail server, else no message is sent out.
Send XML output?
Species the format the output message of the component.
yes – email(s) are formatted as XML text containing To, CC, From, Subject, TextBody, HtmlBody, Headers and Attachments elements with values from the email. When this property is selected, property Send as HTML, if content has HTML is not visible and properties Enforce text?, Enforce html?, Batch Count and Single Batch Mode are visible.
no – text content or HTML content is extracted and sent as output message. In case of multi-part message, only the one of the parts is sent as output. When this value is selected, properties Enforce text?, Enforce html?, Batch Count and Single Batch Mode are not visible and property Send as HTML, if content has HTML is visible. Value for property Batch Count is set to 1 and value for property Single Batch Mode is set to no.
Send as HTML, If Content has HTML
Specifies whether HTML content or plain text content is sent in the output.
yes – If HTML content is present in email, then HTML content is sent in the output. If HTML content is not present but plain text content is present, then plain text content is sent in the output.
no – If plain text content is present in email, then plain text content is sent in the output. If plain text content is not present but HTML content is present, then HTML content is sent in the output.
If set to yes, then the html content will be preferred to be sent in output, if exists. If set to no then text/plain content will be preferred to be sent in output, if exists. This property is visible only if Send XML output? Is set to no.
Single Batch Mode
This option is used to specify whether the component should send each mail in a separate message or in a single XML message.
When this option is set to yes, all emails retrieved are combined into a single XML message and sent to the output.
When this is set to no and value for property Batch size is set to 1, each mail is sent as a separate message.
When this is set to no and value for property Batch Size is set to n – where n is any positive number, n mails are combined into a single XML and sent as a separate message.
This property is only visible when property Send XML output? is set to yes. When property Send XML output? is set to no value for this property is set to no.
Batch Count
This option specifies the number of messages to be combined into a single message. This property is used only if value for property Single Batch Mode is set to no. This property is only visible when property Send XML output? is set to yes. When property Send XML output? is set to no value for this property is set to 1.
For recvMail operation, the input message contains a MessageCount attribute which takes an integer value.
If the message count provided in sample input is less than or equal -1, then it fetches all of the mails from the server.
If the Message Count provided is greater than -1, then the minimum of the Message Count provided and then actual number of messages present in the mail box is computed and fetches that number of mails.
Figure 5: Sample Input
Figure 6: Sample Output
No input and Output schema are generated for the Mail Count operation. For Receive Mail operation, the input schema contains the following elements.
|
Schema Element |
Description |
|
|
<MessageCount> |
Number of messages to be fetched. If the Message Count provided in sample input is less than -1, then it searches in the mailbox for total number of messages and fetches all of them. If the Message Count provided is greater than -1, then the minimum of the Message Count provided and then actual number of messages present in the mail box is computed and fetches those number of mails. |
|
For Receive Mail operation, the output schema looks like:
|
Schema Element |
Description |
|
|
<Emails> |
Emails retrieved from mail box |
|
|
<Email> |
|
|
|
<To> |
Email address of the recipient(s) |
|
|
<From> |
Email address of the sender |
|
|
<CC> |
Email address of recipient(s) to be copied in the mail |
|
|
<Subject> |
Subject of the mail |
|
|
<Body> |
Body of the mail |
|
|
<Text Body> |
Text Body |
|
|
<HTML Body> |
HTML body |
|
|
<Attachments> Attachment Name savedToFile |
Attachments Attachment name in the email Boolean to specify whether attachment is saved. |
|
|
<Headers> Header Name Value |
Headers in Email Header name Header value |
|
This scenario demonstrates the retrieving of e-mails with attachments.
Configure POP3 as described in section 2 for Receive Mail and select the attachment folder in the Interaction Configuration panel to save the attachments, if any. Use Feeder and Display components to send sample input and check the response respectively.
Note: Receive Mail operation receives each mail as a separate message in this case.
Figure 7: Demonstrating scenario 1 with sample input and output
This scenario demonstrates the retrieval of Mail count.
Configure POP3 as described in section 2 for Mail Count operation and use Feeder and Display components to send sample input and check the response respectively.
Figure 8: Demonstrating scenario 2 with sample input and sample output
The component runs on the Peer Server and therefore the file paths and directories mentioned in the CPS should be valid on the machine where the Peer Server is running. If the component fails over to another peer, ensure that the machine on which the secondary Peer Server is running does have the same path available.
If emails contain large attachments, set property Write attachments to file? to yes. The files can be later read using File Reader component, if required.
If emails have to be available for other clients set property Leave messages on Server? to yes.
If property Leave messages on Server? is set to yes, connection pooling should be disabled.
Copyright © 1999-2008, Fiorano Software Technologies Pvt. Ltd. All rights reserved.
Copyright © 2008-2009, Fiorano Software Pty. Ltd. All rights reserved.
This software is the confidential and proprietary information of Fiorano Software ("Confidential Information"). You shall not disclose such Confidential Information and shall use it only in accordance with the terms of the license agreement enclosed with this product or entered into with Fiorano.