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 that applies to the SMTP server; for example: 

[NET_SETTINGS]
smtp_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 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. Possible causes:
  • The DriverParameters argument of the SetSecurity operation contained invalid keywords or data,
  • A protocol error was occurred with the SMTP server.
  • The CA certificate for STARTTLS security driver could not be found or is incorrect. This can occur if the certificate file or location is not correctly specified (using USYS$TLS_PARAM), or if the specified file does not contain the correct certificate. For more information, see SMTP STARTTLS Security Driver.
-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

By default TCP is used when connecting to email servers, but TLS connections are also supported.

For SMTP servers, there are two ways to make use of TLS:

  • By specifying TLS in the initial connection. For example, using a TLS connection with the options defined by the TLS profile smtp_profile in the [NET_SETTINGS] section of the assignment file:
    activate "UPOPMAIL".logonsmtp("TLS:smtp.myorg.com+465:smtp_profile", "", "")
  • By upgrading the initial TCP connection to TLS through the use of the STARTTLS ESMTP extension. In this case, the logonSMTP command must connect using TCP.

To use TLS, you must configure the TLS connector. For a direct TLS connection, you can use usys$tls_params or the [NET_SETTINGS] section of the assignment file. For a STARTTLS connection, you must use USYS$TLS_PARAMS. 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 a password or token. For more information, see SetSecurity, SMTP AUTH LOGIN Security Driver , and XOAUTH2 Security Driver .

When connecting to a Microsoft SMTP server, you must use the SMTP STARTTLS security driver in combination with an authenticating security driver. For more information, see SMTP STARTTLS Security Driver.

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()

Related Topics