POP3Recv

Syntax

POP3Recv (server,user,pass,list[,delete,stsproc,maxmessages,secure {Default zero insecure;1 secure;2 use STARTTLS},verify {Default kTrue}]) Returns status

Description

Note: The flag is set according to whether Omnis was able to make a call to this external command.

This Web command is multi-threaded, allowing another thread to execute in the multi-threaded server while it runs. Note that the same socket cannot safely be used concurrently by more than one thread.

POP3Recv retrieves Internet e-mail messages from a POP3 server into an Omnis list. If an error occurs, the command returns a value less than zero to Status; in this case, all mail may not have been received. The socket opened to the POP3 server is always closed before the command returns. Possible error codes are listed in the Web Command Error Codes Appendix.

Server is an Omnis Character field containing the IP address or hostname of a POP3 (Post Office Protocol Level 3) server that will serve e-mail to the client running Omnis. Examples: pop3.mydomain.com or 255.255.255.254. If the server is not using the default POP3 port (110, or 995 for a secure connection), you can optionally append the port number on which the server is listening, using the syntax server:port, for example pop3.mydomain.com:1234.

User is an Omnis Character field containing the account that receives the mail on the designated server. Usually an account user name, for example, Webmaster.

Pass is an Omnis Character field containing the password for the account specified in the User parameter, for example, Secret.

List is an Omnis list field defined to contain a single column of type binary or character. The column receives the Internet e-mail messages, one per line. The column variable should be large enough to receive the e-mail message, including the header. Note that you can pass the message data stored in each row to MailSplit, in order to parse the message. For correct results with many of the encodings supported by MailSplit you must define the list to have a binary column.

Delete is an Omnis Boolean field which, if true, indicates that the messages will be deleted from the server once they have been downloaded into MailList. The default is false, so messages remain on the server if the argument is omitted.

StsProc is an optional parameter containing the name of an Omnis method that POP3Recv calls with status messages. POP3Recv calls the method with no parameters, and the status information in the variable #S1. The status information logs protocol messages exchanged on the connection to the server.

MaxMessages is an optional parameter which specifies the maximum number of messages to be downloaded by this call to POP3Recv. If omitted, all available messages are downloaded.

Secure is an optional Boolean parameter which indicates if a secure connection is required to the server. Pass kTrue for a secure connection, in which case the built-in security technology will be used, so on Windows ‘Secure Channel’ (Schannel) is used, on macOS ‘Secure Transport’ is used, and on Linux OpenSSL is used.

POP3Recv also supports an alternative secure option, if you pass secure with the value 2, the connection is initially not secure, but after the initial exchange with the server, POP3Recv issues the STLS POP3 command to make the connection secure if the server supports it (see RFC 2595 for details). Authentication occurs after a successful STLS command.

Verify is an optional Boolean parameter which is only significant when Secure is not kFalse. When Verify is kTrue, the command instructs the installed SSL library to verify the server's identity using its certificate; if the verification fails, then the connection will not be established. You can pass Verify as kFalse, to turn off this verification; in this case, the connection will still be encrypted, but there is a chance the server is an impostor. In order to perform the verification, the installed SSL library uses the Certificate Authority Certificates in the cacerts sub-folder of the secure folder in the Omnis folder. If you use your own Certificate Authority to self-sign certificates, you can place its certificate in the cacerts folder, and the installed SSL library will use it after you restart Omnis.

Example

# Retrieve all messages for user lUsername from the POP3 server
# lServer and remove the messages from the server 
Calculate lServer as  'my.pop3.server'
Calculate lUserName as  'myusername'
Calculate lPassword as  'mypassword'
Calculate lDelete as  kTrue
Do  lMailList.$define(lMessage)
POP3Recv (lServer,lUserName,lPassword,lMailList,lDelete) Returns lStatus