|
*WEB/EMAIL |
Email Utility |
The *web/email utility may be called to generate a mime-compliant email message. The file generated will have a long but unique file name assigned by this utility and will have a file extension of .EML. This utility will only work if run from the PxPlus *web directory.
Up to three sub-directories will be created:
|
|
*web/outbox |
Generated email may be left in this directory for later delivery. |
|
|
*web/outbox/new |
All email is generated as a file in this directory until delivery status can be determined, at which time it will be moved or deleted. |
|
|
*web/outbox/sent |
Email may be kept after being sent if parameters dictate that they be saved. |
CALL "*web/email"[,ERR=stmtref], fromaddress$, replyaddress$, toaddress$, ccaddress$, bccaddress$, subject$, message$, attachments$, option$, smtpserver$, servertimeout, linewrapsat, body encoding$, eraseit, errormesg$, senddirectory$, savedfilename$
Where:
|
fromaddress$ |
(Input) Address to be used in the mail header to indicate who is sending the mail. (Only one address is allowed.) See Email Addresses. | ||||||
|
replyaddress$ |
(Input) Address to be used when the recipient of the message wishes to force any replies to be routed to a different address. See Email Addresses. | ||||||
|
toaddress$ |
(Input) Address(es) to whom to send the mail (one or more). See Email Addresses. | ||||||
|
ccaddress$ |
(Input) Address(es) to whom to send a copy of the mail (0 or more). See Email Addresses. | ||||||
|
bccaddress$ |
(Input) Address(es) to whom to send a copy of the mail but whose address is not to be exposed to other recipients (zero or more). See Email Addresses. | ||||||
|
subject$ |
(Input) Subject line for the message. | ||||||
|
message$ |
(Input) Body of the message to be sent. See Message Body. Note: | ||||||
|
attachments$ |
(Input) List of files to attach to the email (null for no file attachments). See Attachments. | ||||||
|
option$ |
(Input) This may be set to "H"igh, "L"ow, or "N"ormal and is used to set the email X-Priority level. Also used to indicate Read Receipt requested (for Priority: H, L or N; for Read Receipt: D and/or R). See Mail Priority/Options. | ||||||
|
smtpserver$ |
(Input) smtpserver$ contains the name of the SMTP server. It should be in the form of SERVER;SOCKET. See Sending or Storing Messages. Example: | ||||||
|
servertimeout |
(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 zero only have an effect on PxPlus version 4.15 or higher.) | ||||||
|
linewrapsat |
(Input) The value in this parameter controls the automated line wrapping of text in the message body. | ||||||
|
bodyencoding$ |
(Input) Mime type for the message$. Text/plain will be assumed, if not given. By specifying a value in bodyencoding$ such as "text/html", the message$ would be assumed to be HTML. | ||||||
|
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.
| ||||||
|
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$ |
(Input) Indicates the directory name to use to save Sent Items. This is valid when eraseit=2 only. | ||||||
|
savedfilename$ |
(Input) Returns the name on disk of the file where the email file was stored after completion. If saving to the outbox, this returns the location and file name within the *web/outbox. | ||||||
|
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.)
Individual email addresses may be specified in simple or complex forms, such as:
support@pvxplus.com
"PVX Plus Support" < support@pvxplus.com >
This makes use of the *web/address utility to validate, verify and correctly format or reformat email addresses.
Where multiple email addresses are supported (toaddress$, ccaddress$, bccaddress$), you may string the email addresses together, separated by any of the following: $8A$ (SEP), $0A$, $0D0A$ or ";" (semi-colon).
The message$ variable may contain up to a maximum of 32,000 characters. However, you may embed coding to represent the insertion of files into the message body. By using a body built of files or a combination of text and files, the maximum body size itself is unlimited.
You can also embed an image into the body of an email. See Embed an Image.
Embedding files within the message body is accomplished by inserting strings of the following format within the message$:
""<<#FILE:filename>>"" or "<<#FILE:filename?option>>"
The file name should contain both the path and the file name of the file. If the file has a file extension, then the mime database will be checked for an entry matching the file's extension, and the mime type will be retrieved. If no mime type is found, then "application/octet-stream" is assumed.
Files will automatically be encoded in one of three ways when being inserted into the final .EML file:
The second format with the ? option suffix allows you to override the actual encoding used or performed on the file.
Valid options are:
|
?Q |
Force file to be encoded in Quoted-Printable format. |
|
?B |
Force file to be encoded in Base64. |
|
?E |
Do not encode. File is assumed to already exist in Quoted-Printable format. |
|
?6 |
Do not encode. File is assumed to already exist in Base64 format. |
|
?P |
Declares the file as "text/plain". Encoding will depend on usage. |
|
?I |
Include file as is. Do not encode the file. Do not put mime headers before the file's content. The utility will simply wrap mime boundaries around the inserted file. By using this feature, you can manually encode mime-based files of any format or layout such as multi-part/relative and include that into this email file. |
Using this technique, it is very simple to create a message from an HTML page:
message$="<html><head><title>..</html>"
bodyencoding$="text/html"
or simply
message$="<<#FILE:/somefile.html>>"
Since this message body is built from a file, the mime type will be worked out automatically, and therefore, bodyencoding$ need not be set. However, you can also combine bodies encoded one way with files encoded another:
message$="<html><head><title></title>..</head><<#FILE:/somewhere.txt>>
</body></html>"
bodyencoding$="text/html
Whenever there is a file inside the message body, the file will always start on a new line; it will not continue an existing line. If the message body is built of text and files, and both the text and all of the files turn out to be of mime type "text/plain", then the message will be built as a single body and not as multiple pieces. Other than this rule, the message body and the entire email will be built as a "multi-part/mixed" mime with boundaries between each component.
A few methods are available to embed an image into the body of an email. Different email clients provide varying support for the different types of embedded images.
The most compatible way to embed an image that works in all email clients tested is to host the image on a server and point to it via the HTML tag <img src='url'/>.
Example:
message$="<html><head></head><body><p>Check out the new logo</p><p> <img src='https://www.yourcompany.com/newlogo.png' /></p><p>Regards.</p></body></html>"
There are other less compatible ways to embed an image.
One way is to include the image as an attachment and use the HTML tag <img src='cid:filename'/> to reference the attached image. The filename must match the filename used in attachments$.
Example:
message$="<html><head></head><body><p>Check out the new logo</p><p> <img src='cid:newlogo.png' /></p><p>Regards.</p></body></html>"
attachments$="newlogo.png"
Another way is to convert the image into Base64 and use the HTML tag <img src='data:image/png;base64,imageData'/>.
Example:
OPEN (HFN,ISZ=-1)"newlogo.png"
READ RECORD (LFO,SIZ=NUM(FIN(LFO,"FileLength")))imgdata$
CLOSE (LFO)
base64img$=CVS(imgdata$,"ASCII:BASE64",0)
message$="<html><head></head><body><p>Check out the new logo</p><p> <img src='data:image/png;base64,"+base64img$+"' /></p><p>Regards.</p></body></html>"
(Support to embed an image was added in PxPlus 2020.)
The attachments$ may contain a separated list of file names - the files to be attached to the email message. The separator may be $8A$ (SEP), $0A$, $0D0A$ or ";" semi-colon.
No special formatting is used or needed; however, the ?options are available just as in the message body and have the same effects in the message body.
Example:
attachments$="C: \file1.htm;C:\image.bmp;C:\somefile.mine?B;C:\someotherfile.ok?Q"
If the file has a ? option suffix, then the encoding of the file will be forced; otherwise, the file's extension will be used to find the mime type in the mime type database. Encoding will be Quoted-Printable for any mime types starting with "text/"; all others are encoded as Base64.
The mime type database is a file named "*web/webserv.mim". This is a keyed file, which uses the file extension as the key. At present, the only available method for modifying, adding or deleting mime types is through the use of the PxPlus Web Server Configuration screen.
Alternatively, you may modify the mime type file directly. The file should be opened with IOL=*, and all file name extensions must be written to the file in lowercase.
The following table describes the actual internal email priority settings that will be incorporated into the email header based on the value you supply in the option$ value:
|
Value |
X-Priority |
X-MSMail-Priority |
Importance |
|
L |
5 |
Low |
Low |
|
N |
3 |
Normal |
Normal |
|
H |
1 |
High |
High |
|
D |
Return a Read Receipt, also known as a Disposition Header. | ||
|
R |
Return a Delivery Receipt, also known as a Return Receipt. | ||
Not all email tools will respond to priority settings, or they may not respond to the specific email header tags of "X -Priority:" or "X -MSMail-Priority:" or "Importance:".
For all text-based messages or files, the character set will be reported as "us-ascii" unless otherwise overridden by the global variable %EMAIL_CharSet$.
Email may be stored in an outbox (*web/outbox) by specifying NULL or "< >" for the smtpserver$ argument. At no time will this program read messages from the outbox and attempt to deliver them. If an smtpserver$ is specified, then the message will attempt to post itself immediately after it has been generated.
If an email cannot be completely generated, then it will not be sent to any recipients. The reason will be placed in errormesg$.
If, during the course of generating an email, one of the addresses in any of the address fields is found to be invalid, then the email will not be sent to any recipients. A list of bad email addresses will be returned in errormesg$.
If, during the course of posting the email, one of the recipients is found to be invalid, then the email will be posted to all valid recipients.
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 *web/testemail utility makes it easier and more convenient to work with the *web/email utility. Using only a few options, it allows you to send a "test" email and will output the *web/email command needed to send an email. It will also display helpful error messages to assist you in quickly resolving any issues.
CALL "*web/testemail;test_name",from$,smtp_server$,username$,password$,to$
Where:
|
test_name |
(Input) One of the following options can be used:
| ||||||
|
from$ |
(Input) Address to be used in the mail header to indicate who is sending the mail. (Only one address is allowed.) | ||||||
|
smtp_server$ |
(Input) The SMTP Server Name or IP address to be used to send the email. | ||||||
|
username$ |
(Input) Your username for the SMTP server, usually your email address. | ||||||
|
password$ |
(Input) Your password for the SMTP server. | ||||||
|
to$ |
(Input) Address(es) to whom to send the mail (one or more). |
Example:
The following CALL will send this sample email to test@yourserver.com from test@myserver.ca:
Subject: "Test Please Ignore"
Message: "Hi this is a test from PxPlus
Hello World"
CALL "*web/testemail;TEST","test@myserver.ca","smtp.myserver.ca","test@myserver.ca","mypassword","test@yourserver.com"
(The *web/testemail utility was added in PxPlus 2016.)