Web Utilities

*WEB/SMTP

SMTP Utility

Description

The *web/smtp utility may be called to send an email message to a server, which is running an SMTP mail daemon. This utility will only work if run from the PxPlus *web directory.

Up to two sub-directories will be created:

	*web/outbox	Email awaiting delivery.
	*web/outbox/sent	Email files will be kept in this directory after being sent, depending on the value of eraseit.

Calling Sequence

CALL "*web/smtp", filename$, smtpserver$, timeout, eraseit, errormesg$

Where:

filename$

(Input) Path and file name of an email message file to send to an SMTP server. If filename$ is null, then all files ending in ".EML" in the *web/outbox directory will be sent. See File Name.

smtpserver$

(Input) smtpserver$ contains the name of the SMTP server. It should be in the form of SERVER;SOCKET.

Example:

smtp.pvxplus.com;25

If no socket number is specified, then a default SMTP socket number of 25 is used.

If no Server Name is specified (smtpserver$ is NULL) or contains the word "<<OUTBOX>>", then the email will be generated and left in the *web/outbox directory.

If the SMTP server requires authorization, this field can contain the UserID and Password.

For a connection secured via SSL/TLS, you must add "-secure" following the Port Number. To use an SMTP server that is protected by STARTTLS encryption (usually ones that run on Port 587), the "-secure" must be left out of the SMTP server string. See SMTP Server.

timeout

(Input) If non-zero, this parameter specifies the timeouts for sending directly to the SMTP server.

If 0 (zero), the timeout value will be set to 60 seconds. (Values greater than 0 only have an effect on PxPlus version 4.15 or higher.)

eraseit

(Input) The value specified in this parameter indicates whether the program is to delete or save the generated .EML file that is output by this program. It is used only if the message has been successfully sent.

Possible values are:

0	Leave the message file alone. *(Default)*
1	Delete the Sent message file.
2	Save the Sent message to a Sent folder.

errormesg$

(Output) If an error is encountered during the compile of an email or in the course of sending an email, the program will load this variable with a textual description of the problem and then exit with an error. See Errors and Results.

Debug Tracing

To assist with debugging, an email utility trace can be enabled by setting the global variable %trace_email to 1 and opening the program TraceWindow. This will output the utility's actions and any errors to the trace window; however, it will not trace the entire program.

(Tracing was added in PxPlus 2018.)

SMTP Server

If the SMTP server to which you are connecting requires authorization, you can include the UserID and Password in the smtpserver$ value following the server name and port number:

server;port;userid;password

For a connection secured via SSL/TLS, you must add "-secure" following the Port Number in the SMTP server string.

Example:

smtp.gmail.com;465-secure;userid;password

To use an SMTP server that is protected by STARTTLS encryption (usually ones that run on Port 587), the "-secure" must be left out of the SMTP server string. This is because STARTTLS encryption requires making an unsecure connection and negotiating a secure connection.

Example:

mail.abccorp.com;25;userid;password

File Name

The filename$ parameter may contain either no file name or one file name. If this parameter is null, then all files with an extension of .EML that exist within the *web/outbox directory will be sent to the smtpserver$ specified. If a file name is given, then it must contain only one email message.

Errors and Results

If, during the course of posting the email, one of the recipients is invalid, then the email will be posted to all it can be, and the ones that are not able to be posted will be returned in the errormesg$ field.