LogonSMTP

Log on to the designated SMTP server via TCP or TLS.

LogonSMTP(NetworkConnectionString,"","")

where NetworkConnectionString is:

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

TCP Example: activate "UPOPMAIL".logonsmtp("smtp.myorg.com", "", "")
TLS Example: activate "UPOPMAIL".logonsmtp("TLS:smtp.myorg.com+465:smtp_profile", "", "")

Parameters

Parameter Type Direction Description
NetworkConnectionString string IN Information required to connect to the SMTP server
NetworkConnector     Three-letter code for the network connector; one of TCP or TLS. If omitted, the default is TCP.
HostId     SMTP server that will be used to send email.
PortNumber     Port number appropriate to the protocol. If omitted, the default is 25 for TCP and 465 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 The UserName and Password parameters are not used and must be empty strings.
Password string IN

Return Values

Values Returned by LogonSMTP in $status
Value Description
0 Success
< 0 Failure
-2 UserName or Password is specified
-3 Already logged on
-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 SMTP server.
-9 Network problems or invalid server name

Description

The LogonSMTP operation is used to log on to the designated SMTP server, leaving the connection open so subsequent, multiple SendMail operations do not open and close the connection for each mail. After you perform LogonSMTP, the Server parameter in subsequent SendMail operations is ignored and the connection remains open.

After all mails have been sent, use LogoffSMTP to close the connection.

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.

When using TLS to connect to, for example, a Gmail server, you may need to use the SMTP AUTH LOGIN or XOAUTH2 security driver to provide a user name and password or token. For more information, see SetSecurity, SMTP AUTH LOGIN Security Driver, and XOAUTH2 Security Driver .

Note: It is not possible to connect to Outlook or Office 365 using TLS. Microsoft uses the starttls extension for TLS and does not support direct TLS connections.

Used After SetSecurity

If a security context has been defined by SetSecurity, the LogonSMTP operation tries to establish that context. If it is successful, the security context is locked until a LogoffSMTP call is performed. If the LogonSMTP fails, the security context can be in one of two states depending on the failure.

If the operation discovers that the driver’s functionality is not supported (-7), or if the security context could not be established (-8), the connection to the SMTP 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 LogonSMTP and LogoffSMTP calls, and the next call to SetSecurity establishes a completely new security context.

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

The following example opens the connection to the SMTP server, performs a number of SendMail operations (ignoring the server parameter), then finally closes the connection to the SMTP server.

activate "UPOPMAIL".logonsmtp("smtp.myorg.com", "", "")
activate "UPOPMAIL".sendmail("", header, body, attr, 0)
...
activate "UPOPMAIL".logoffsmtp()