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; 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 UserNameand Password are not used . Instead, the user and access token from the context are used.

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 SMTP 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 in the [NET_SETTINGS] section:

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