LogonMail

Log on to the designated POP server using TCP or TLS.

LogonMail(NetworkConnectionString, UserName, Password)

where NetworkConnectionString is:

{NetworkConnector:}HostId{+PortNumber}{:TLSProfile}

TCP Example: activate "UPOPMail".LogonMail ("pop.myorg.com", "a_user", "s3cret");

TLS Example: activate "UPOPMail".LogonMail ("tls:pop.myorg.com+995:pop_profile", "a_user", "s3cret");

Parameters

Parameter	Type	Direction	Description
NetworkConnectionString	string	IN	Information required to connect to the POP server
NetworkConnector			Three-letter code for the network connector; one of `TCP` or `TLS`. If omitted, the default is `TCP`.
HostId			POP3 server name or IP address
PortNumber			Port number appropriate to the protocol. If omitted, the default is `110` for TCP and `995` for TLS.
TLSProfile			Name of a TLS connection profile that applies to the POP server; for example: [NET_SETTINGS] pop_profile = verify_server=1, ca_certificate=cacert.pem, verify_server_name=0 Applicable only if NetworkConnector is `TLS`. For more information, see TLS Connection Profiles.
UserName	string	IN	ASCII string specifying the user name. Note: If a security context has been specified (using SetSecurity), the UserName and Password parameters are not used. Instead, the user and access token from the context are used. You can therefore specify the UserName and Password as empty strings (`""`).
Password	string	IN	ASCII string specifying the password for the UserName.

Return Values

Values Returned by LogonMail in $status
Value	Description
0	Success
< 0	Failure
-2	Log on sequence failed due to invalid user name or password, or mailbox is already locked
-3	Already logged on
-5	Initialization error
-7	Email server does not support security driver functionality
-8	Security context could not be established. Either the DriverParameters argument of the SetSecurity operation contained invalid keywords or data, or some protocol error occurred with the POP server.
-9	Socket error, or incorrect server name

The LogonMail function performs the logon to the POP server, which uses the security context that was established by the calls to SetSecurity.

Connecting over TLS

Uniface supports connection both TCP and TLS connections to mail servers. By default TCP is used.

To use TLS, you must configure the TLS connector using usys$tls_params or the [NET_SETTINGS] section of the assignment file. For more information, see Configure the TLS Connector to Use Certificates.

To validate the server, you will need the CA Root certificate that signed the server's certificate. For more information, see Digital Certificates and Certificate-Based Authentication

Used After SetSecurity

It is possible to use the XOAUTH2 security driver to connect to a POP server by calling the SetSecurity operation before calling LogonMail.

The LogonMail operation tries to establish that context. If it is successful, the security context is locked until a LogoffMail call is performed. If the LogonMail fails, if the security context could not be established (-8), the connection to the POP server is closed, but the security context is not removed. If desired, it can be used against another SMTP server. However it is as if there had been successful LogonMail and LogoffMail calls, and the next call to SetSecurity establishes a completely new security context.

For any other error, it is as if no LogonMail call had been done and the next call to SetSecurity appends the security driver to the security context.

Logging on to a POP3 Server

The LogonMail operations must be used in conjunction with an activate statement, along with reference to the UPOPMail signature that is required to use the mail integration functions:

Using the default TCP connection:

activate "UPOPMail".LogonMail ("pop.myorg.com", "pzwarts", "guess");

Using an explicit TCP connection:

activate "UPOPMail".LogonMail ("tcp:pop.myorg.com+110", "pzwarts", "guess");

Using a TLS connection with the options defined by the TLS Profile pop_profile in the [NET_SETTINGS] section of the assignment file:
```
activate "UPOPMAIL".logonmail("TLS:pop.myorg.com+995:pop_profile", "", "")
```