POP3 component is used to connect to a mail server/News server and retrieve emails/news articles using POP3/IMAP/NNTP protocol. It uses the JavaMail API.
The component supports these functions:
- Retrieve emails/news articles from the mail/news server.
- Fetch the email/news count on the mail/news server.
- Verify signature, decrypt mail and MDN
Configuration
Managed Connection Factory
The following properties can be configured in the Managed Connection Properties panel of CPS.
Figure 1: Managed Connection Panel of POP3
General attributes
Protocol
Specifies the protocol used to retrieve emails.
- POP3 – POP3 protocol is used to retrieve emails. The property Folder to pick mails is not visible if this value is selected.
- IMAP – IMAP protocol is used to retrieve emails. The property Folder to pick mails is visible if this value is selected.
- NNTP – NNTP protocol is used to retrieve news articles. The property Newsgroup to pick news articles is visible if this value is selected.
- MailserverURL – Specifies URL at which the mail server is hosted.
Connection Configuration
Click the ellipses button to configure the properties.
Figure 2: Connection Configuration properties
MailServer URL
URL of the mail server.
MailServer Port
Specifies port number on which the mail server accepts POP3/IMAP/NNTP connections. The default port for NNTP is 119 and IMAP is 143.
Additional Properties
Additional properties which can be used for creating connection can be specified here. For instance, to enable debug in Javamail set property 'mail.debug' to 'true'.
For example, to retrive mails from gmail, we need to set the "MailserverURL" and "MailServer Port" properties to "pop.gmail.com" and "995" respectively. Apart from this we need to provide the following additional properties:
- mail.pop3.starttls.enable=true
- mail.pop3.auth=true
- mail.pop3.socketFactory.class=javax.net.ssl.SSLSocketFactory
- mail.pop3.socketFactory.fallback=false
- mail.pop3.socketFactory.port=995
Authentication Configuration
Authentication details to connect to the POP3 server. Click the ellipses button to configure the properties.
Figure 3: Authentication Configuration properties
Username
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.
Use Custom Encryption
Folder to pick mails
Specifies folder name from which emails are retrieved. This option is displayed only when the Protocol property is set to "IMAP".
News group to pick articles
Specifies Newsgroup name from which news articles are retrieved. This option is displayed only when the protocol property is set to "NNTP".
Expert properties
Enable the Show Expert Properties checkbox to make the properties visible.
Figure 4: Managed Connection Factory with the Expert Properties view enabled
Use Connection Details From Input
Parameters to create the connection can be specified in the input message when this property is set to true. If this property is selected the validation errors in the managed connection factory panel of the CPS are treated as warnings. So the user can bypass this step without giving valid configuration and complete the configuration of the component. If valid properties are not provided even in the input message exception will be thrown at runtime.
ConnectionTimeoutinms
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 ErrorConfigurationPanel.
Timeout in ms
Socket I/O timeout value in milliseconds. If any operation requires more than the specified time then the operation fails.
Connection Pool Params
Please refer to the Connection Pool Params section in the Common Configurations page for details.
SSL Security
Please refer to the SSL Security section in the Common Configurations page for details.
AS1 Configuration
Enable AS1
Select this option to enable AS1 and provide signing, encryption and MDN configuration by clicking the ellipsis button of AS1 SSL Configuration property.
Signature Configuration
Figure 5: Signature configuration details
SignMail: Select to sign mail and provide algorithm and key store details to be used for signing.
Alias: Partner public key certificate alias should be configured.
Encryption Configuration
Figure 6: Encryption configuration details
Encrypt Mail: When this option is selected, mail will be encrypted with the provided algorithm and Keystore details.
Server connection can be tested from within the CPS by clicking the Test button in the Connection Properties panel.
Alias: Host private key alias should be configured.connection can be tested from within the CPS by
Keystore Configuration
Refer the section SSL Configuration – Client perspective to understand configure Keystore.
Interaction Configuration
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 7: Interaction Configuration panel
Attributes
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?, Article status file
- 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?, Article status file
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.
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 the figure below.
Figure 8: 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 the figure below. New line characters (/n or 
) in text content are converted to break line symbols (<BR>) in html content.
Figure 9: 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.
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.
Sample Input and Output
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.
Sample Input
Figure 10: Sample Input
Sample Output
Figure 11: Sample Output
Input Schema
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 numbers of mails. |
Output Schema
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> | Attachments |
<Headers> | Headers in Email |
Functional Demonstration
Scenario 1
This scenario demonstrates the retrieving of e-mails with attachments.
Configure POP3 as described in section Configuration and Testing 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.
Figure 12: Demonstrating scenario 1 with sample input and output
Scenario 2
This scenario demonstrates the retrieval of Mail count.
Configure POP3 as described in section Configuration and Testing for Mail Count operation and use Feeder and Display components to send sample input and check the response respectively.
Figure 13: Demonstrating scenario 2 with sample input and sample output
Useful Tips
- 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 Writeattachmentstofile? 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 LeavemessagesonServer? to yes.
- If property LeavemessagesonServer? is set to yes, connection pooling should be disabled.
- If the component is used to connect to a mail server that is SSL enabled, set the value of property 'mail.pop3.ssl.enable' in case of POP3 and 'mail.imap.ssl.enable' in case of IMAP to 'true' in Additional Properties in Connection Configuration.
- If the component is used to connect to a mail server that is SSL enabled and the component is running in-memory, Enable SSL in component configuration and provide the truststore location and password. In general, this truststore is %JAVA_HOME%\jre\lib\security\cacerts.