POP3 Adapter

To receive and delete mails from a POP3 server, you can use the POP3 Adapter. The POP3 parameters can be provided statically in the component diagram or dynamically via action script.

Example File (Builder project Add-ons/EMail):

<your example path>\Add-ons\EMail\uml\pop3.xml

Receiving Mails (Static Usage)

In order to receive a mail from a POP3 server, use action getMessage with the POP3 Adapter. With static usage of the adapter, the POP3 parameters are provided in the component diagram via the alias that is used on the adapter action.

Figure: Static Usage of the POP3 Adapter

Action get next message in the activity diagram above has an input parameter deleteOnServer. This parameter is of type Boolean and indicates whether the message is to be deleted after it has been fetched by the POP3 adapter. If the parameter is set to true, a DELE command is send to the POP3 server and the message will be flagged as to be deleted.

When the whole SOAP request (i.e. not only the activity where the POP3 adapter is modeled) has come to an end without an exception, the POP3 session will be closed with a QUIT command, and the POP3 server deletes the messages finally.
If there is an exception during the whole processing, the POP3 session will be closed with a RSET command, and all marks are removed from the messages. This means that no message will be deleted.  

Parameter deleteOnServer can not be specified in the component diagram. Even in case of a static usage, it has to be modeled as a dynamic parameter.

The POP3 adapter does not retrieve all messages at once - the output of the adapter is a single message object. If there is more than one message in your server's inbox and you want to fetch all of them, you will have to do it one by one by separate getMessage calls. To get a next  message from the mail server, you have to draw the control flow back to the POP3 adapter and start another getMessage call.

Output of a POP3 Adapter call is parameter message, an object of type POP3Message. The whole content of the message is stored as a Blob in attribute content (see POP3 Adapter Parameter Types). Hence, the content must be decoded and separated into parts to make it readable. This is done by a MIMEConverter in sub activity extractMessage (for more details refer to MIME Converter).

Figure: Decode MIME-Parts

Sometimes it is necessary to access the POP3 headers as in action build out message in the picture above. Attribute pop3Header of class POP3Message holds the raw POP3 headers.

Receiving Mails (Dynamic Usage)

Figure: Dynamic Usage of the POP3 Adapter

In the dynamic case - unlike the static usage of the POP3 adapter, all input parameters of the adapter are passed at runtime (as shown in the figure above).

Delete and  Commit/Rollback Received Mails

Instead of setting flag deleteOnServer while receiving the mail, you can send a delete command later in your processing as well. For that purpose, use the POP3 adapter with action delete. To identify the message to be deleted, provide a message and a sessionID which have been both received previously with a getMessage action.

Figure: Delete, commit, rollback on the POP3Servers

If the deleteOnServer flag has been set, the messages on the POP3 server are deleted after the SOAP request (transaction) has ended without an exception. But sometimes, e.g. when processing a large amount of messages, it might be necessary to commit or rollback the deletion of the message on the POP3 server manually.
In order to do this, use the POP3 Adapter with action commit respectively rollback. Only input you need is the sessionId, which has been received earlier with the getMessage action.