|
*WEB/SMTP |
SMTP Utility |
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. |
If connecting to an SMTP server that supports/requires OAuth2 authentication instead of User Name/Password authentication, you can pass in an OAuth2 access token. The program will use OAuth2 authentication instead of User Name/Password authentication.
To get a valid access token, you will need to have set up OAuth2 with the server provider. Using the credentials given to you and their authorization and/or token URLs, you can request an access token.
You can use *plus/web/request for the grant_type=client_credential OAuth2 flow, or you can use the *obj/OAuth2 object for the grant_type =authorization_code flow to get access tokens.
See Access OAuth2 Restricted Web Service for an example of getting the access token for a PxPlus Web service.
See Submitting a Web Request for information on using the *plus/web/request utility.
(OAuth2 support for the *web/smtp utility was added in PxPlus 2025.)
CALL "*web/smtp"[,ERR=stmtref], filename$, smtpserver$, timeout, eraseit, errormesg$[, sentdirectory$[, accesstoken$]]
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:
| ||||||
|
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. | ||||||
|
sentdirectory$ |
Indicates the directory name to use to save Sent items. This is valid only when eraseit=2. | ||||||
|
accesstoken$ |
OAuth2 access token. If non empty, OAuth2 authentication will be used with the SMTP server. (Defaults to empty string; i.e. no OAuth2.) (accesstoken$ was added in PxPlus 2025.) | ||||||
|
stmtref |
Program line number or statement label to which to transfer control. |
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.)
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
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.
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.
Example 1 - To connect to SMTP server with a password:
call "*web/smtp","out/","smtp.myserver.ca;587;example@myserver.ca;mypassword",60,0,ERRMSG$
Example 2 - To connect to SMTP server with an OAuth2 access token:
call "*web/smtp","out/cur.eml","smtp.myserver.ca;587;example@myserver.ca",60,0,ERRMSG$,"",ACCESSTOKEN$
*WEB/EMAIL Utility
*WEB/TESTEMAIL Utility
*WEB/POP3 Email Retrieval Utility