MAILSEND

9.1

 

The MAILSEND instruction sends an electronic mail message with associated attachments using the SMTP protocol. The instruction uses the following format:

 

 

[label]

MAILSEND

{outgoing},{sendto},{sendfrom}:

{subject},{message}[,{options}]

 

Where:

label

Optional. A Program Execution Label.

Outgoing

Required. A previously defined Character String Variable or literal that contains the SMTP outgoing mail server name (URL) or IP address.

sendto

Required. A previously defined Character String Variable or literal that contains the e-mail address(es) of the recipients.

sendfrom

Required. A previously defined Character String Variable or literal that contains the single e-mail address of the sender.

subject

Required. A previously defined Character String Variable or literal that contains the subject of the message.

message

Required. A previously defined Character String Variable or literal that contains the message body to be sent.

options

Optional. One or more of the options or values described below.

Flags Affected: ZERO, EOS

Note the following:

  1. Multiple {sendto} addresses may be specified and are separated by commas.

  2. The default message type is text/plain. This can be modifed by the TYPE option below.

  3. The {options} that may follow the required operands are:

    4.  

    Option

    Meaning

    *ATTACHMENT={svarlit}

    This optional parameter specifies one or more file names that identify the files sent with the e-mail message as attachments. When more one file name is specified, the semi-colon (;) character separates the file names.

    *BCC={svarlit}

    This optional parameter specifies the e-mail address or addresses of the Blind Copy recipients. This parameter may contain one or more recipient addresses. If more than one e-mail recipient is specified, a comma separates the e-mail addresses.

    *CC={svarlit}

    This optional parameter specifies the e-mail address or addresses of the Copy recipients. This parameter may contain one or more recipient addresses. If more than one e-mail recipient is specified, a comma separates the e-mail addresses.

    *DSNRECEIPT={svarlit}

    This optional parameter specifies this e-mail requires a Delivery Service Notification as specified by the {svarlit} string. The {svarlit} string can be specified as follows:

     

    *DSNRECEIPT="Never"

    or

    *DSNRECEIPT="Success,Failure,Delay"

    Where:

    Never

    No return receipts are returned. This string option cannot be combined with other options.

    Success

    There will a notification on the successful delivery of message. This option can be combined with Failure/Delay.

    Failure

    There will be a notification when a delivery failure occurs. This option can be combined with Success/Delay.

    Delay

    This will be a notification when the delivery of a message is delayed. This option can be combined with Success/Failure.

     

    When combining options, the commas must be used.

    *ERROR={svar}

    This optional parameter specifies a Character String variable that receives any error information returned by the MAILSEND instruction. If this parameter is not specified, error information is stored in the S$ERROR$ variable.

    *ERRORLIST={svar}

    This optional parameter specifies that alll email addresses rejected by the SMTP mail server are stored in the {svar} variable. (9.6B) The MAILSEND instruction attempts to send every email address specified in {sendto}, *CC, and *BCC. The rejected email addresses are stored along with the Mnn error data in {svar}. The rejected email address is separated from the Mnn data using a comma (,) character. Multiple rejected email addresses are separated by a semi-comma (;) character.

     

    Format of *ERRORLIST data:

     

    <emailadr1>,Mnn Subcode: sss[;

    <emailadr2>,Mnn Subcode: sss OsError: ooo[;

    ...]]

     

    Example of *ERRORLIST data:

     

    myemail@mailserver.com,M03 Subcode: 44

     

    Note:

    The MAILSEND *ERRORLIST only returns the email addresses that are rejected by the SMTP mail server. The MAILSEND instruction does not evaluate nor attempt to qualify any email address formats that are being provided by the end-user application.

    *MESSAGEID={svarlit}

    This optional parameter specifies the SMTP 'Message-ID:' header string included in the email message. (10.7)

     

    Example Keyword to include in your MAILSEND instruction:

     

     *MESSAGEID="uniqueidentity@somecompany.com"

    *MDNRECEIPT

    This optional parameter requests that a client program receipt will be returned when the recipient reads this e-mail.

    *OPENSSL

    This optional parameter enables the SSL ( Secure Sockets Layer ) support if the OpenSSL libraries have been installed on the Workstation where the PLB runtime is executing. See information for OpenSSL libraries using this link: (http://www.openssl.org/) (9.4)

    *OPTIONS={nvar|dnum|xnum}

    This optional parameter specifies a bit mask value that defines special operational behaviors for the MAILSEND instruction. This parameter value can be a previously declared numeric variable or a number that is specified as a decimal or hexadecimal value. Also, the bit mask values are described in the Note (4.) table.

    *PASSWORD={svarlit}

    This optional parameter specifies the password for the login to the {outgoing} e-mail server.

    *PORT={dnumnvar}

    This optional parameter specifies the port number used when logging on to the {outgoing} e-mail server. If this parameter is not specified, the default port number of twenty-five (25) is used.

    *RETURN={svarlit}

    This optional parameter is only valid when the *DSNRECEIPT keyword is used. This parameter specifies the recommended format of the return receipt that is being requested by the *DSNRECEIPT keyword. The {svarlit} string can be specified as follows:

     

    RETURN="Full"

    or

    *RETURN="Hdrs"

    Where:

    Full

    The full message will be returned with the receipt. This option is not combined with the other option.

    Hdrs

    The returned receipt should only contain the message headers.

     

    The options are mutually exclusive.

    *REPLYTO={svarlit}

    This optional parameter specifies the e-mail address that a recipient will send a reply to when responding to this email.

    *STARTTLS

    This option invokes a SMTP extension to use TLS (Transport Layer Security) which provides private and authenticated communications. This option first accesses an email server using unsecured communications to received the server configuration. If the server configuration is set to support STARTTLS, the MAILSEND establishes a SSL secured connection before continuing to send the email message. The *OPENSSL and the *STARTTLS options cannot be used in the same MAILSEND instruction. See information for OpenSSL libraries using this link: (http://www.openssl.org/) (9.7A)

    *SUNDM={hostname/ip]

    This optional parameter specifies a character string or literal that identifies the Data Manager used when sending an email. The format of the {hostname/ip} string can include a DNS host name or IP address plus a port number. (See below.) (9.4C)

    *TIMEOUT={dnumnvar]

    This optional parameter specifies the timeout value used when communicating with the {outgoing} e-mail server. If this parameter is not specified, the default timeout of sixty (60) seconds is used. There are no restrictions placed on the value specified. This timeout value only starts and takes affect after the socket connection has been established.

    *TRACE={svarlit}

    This optional parameter specifies the file name created to store all data messages sent and received when communicating with the {outgoing} e-mail server. Note that a trace file is overwritten for a each MAILSEND instruction.

    *TRACEAPPEND={svarlit}

    This option allows the trace data to be appended to an existing trace log file. If the trace log file does not exist, it is created. The TRACE and TRACEAPPEND options cannot be specified in the same MAILSEND instruction.

    *TYPE={dnumnvar}

    This optional parameter specifies the body Content-Type used for the e-mail message. The {dnumnvar} value may be one of the following values. Any other values are considered invalid and the default value of zero is used.

    0 - The Content-Type is text/plain with the character set of us-ascii specified. The e-mail body is a simple text message with lines delimited with a carriage-return line-feed sequence.

    1 - The Content-Type is text/html. The e-mail body is in HTML format with lines delimited with HTML line break or paragraph sequences.

    2 - The Content-Type is text/richtext. The e-mail body is in a richtext e-mail format. RFC 1341 describes this simple subtype.

    3 - The Content-Type is text/plain with the character set of iso-8859-1 specified. The e-mail body is a simple text message with lines delimited with a carriage-return line-feed sequence.

    4 - The Content-Type is set to 'text/html; charset=utf-8'. In this case, the e-mail body is in HTML format with lines delimited with HTML line break or paragraph sequences. Also, the e-mail body encoding is specified to be UTF-8. (10.7)

    *USER={svarlit}

    This optional parameter specifies the username used for the login to the {outgoing} e-mail server.

     

  4. The {options} value specified by the *OPTIONS parameter can be a numeric variable, a decimal number, or a hexadecimal number. The bit mask values are used to invoke different behaviors for the MAILSEND operations (10.1B). The bit mask values are defined as follows:

    5.  

    Value

    Description

    0x10

    16

    When this bit is set to 1, the MAILSEND instruction sends an email the same as described for the OPENSSL keyword. This bit value cannot be used if $MAIL_FLAG_STARTTLS is used. See information for OpenSSL libraries using this link: (http://www.openssl.org/) (10.3)

    0x80

    128

    When this bit is set to 1, the MAILSEND instruction sends an email the same as described for the STARTTLS keyword. This bit value cannot be used if $MAIL_FLAG_OPENSSL is used. (10.3)

     

    Note:

    1. A M23 subcode 48 error occurs if both $MAIL_FLAG_SSL and $MAIL_FLAG_STARTTLS bit values are used at the same time in the OPTIONS value.

    2. If the *OPENSSL or *STARTTLS keyword is used, the OPTIONS bit values $MAIL_FLAG_OPENSSL and $MAIL_FLAG_STARTTLS are ignored. See information for OpenSSL libraries using this link: (http://www.openssl.org/)

    0x100

    256

    When this bit is set to one (1), the MAILSEND sends all attachments using the 'Content-Disposition: attachment; filename="file.ext"' header field. If this bit is set to zero (0), the MAILSEND sends all attachments using the 'Content-Disposition: inline; filename="file.ext"' header field.

     

    Note: Using the 'Content-Disposition: attachment' header field may cause the email client to present the attachments where they are separate from the main body of the mail message.

    0x200

    512

    Setting this value causes the MAILSEND instruction to first attempt to load the OpenSSL DLLs (ssleay32.dll and libeay32.dll) if they exist in the 'openssl' sub-directory located in the directory specified by the PLB_SYSTEM keyword found in the PL/B runtime INI file. Note, this flag option is obsolete for release 10.7 and newer releases.

     

    Example:

     

    PLB_SYSTEM=c:\Sunbelt\plbwin.103A\code

     

    The OpenSSL DLLs (ssleay32.dll and libeay32.dll) must exist in the following directory to be used.

     

    c:\Sunbelt\plbwin.10>\code\openssl

    0x400

    1024

    Setting this bit ($MAIL_FLAG_USEIPV6) in the *OPTIONS value causes the MAILSEND instruction to expect and process the {outgoing} parameter as an IPV6 URL or address. In this case, the {outgoing} parameter must resolve to be a valid IPV6 socket connection. (10.7)

     

  5. The *ATTACHMENT, *TRACE, and *TRACEAPPEND options support the file name conventions using the PLBENV_ and PLBVOL_ keywords and Data Manager specifications.

  6. The *OPENSSL option (added in version 9.4) does not support private certificates.

  7. It is the user's responsibility to keep the latest OpenSSL libraries up to date for any enhancements and bug fixes in the libraries.

  8. A MAILSEND error 99 with a subcode 64 or 65 occurs if the *OPENSSL keyword is used and an error occurs accessing or using the OpenSSL libraries. The subcode 64 indicates the runtime is unable to load the OpenSSL libraries. The subcode 65 indicates the runtime is unable to create a SSL connection using the OpenSSL libraries.

  9. SSL is a public key encryption algorithm. An SSL server process has a key pair - a private key and a public key. The public part of the key is freely distributable to encrypt data. The data cannot be decrypted with the public key. The private key that is kept secret on the server is what is required to decrypt the data.

  10. When a SSL client connects to a SSL server, the server gives the public key to the client as part of the normal SSL connection process. Because of the way this works, no default encryption key exists on the client because the public key cannot be used to decrypt data.

  11. If the instruction executes successfully, the ZERO flag is set. If the command fails, the ZERO flag is cleared and error information is stored into S$ERROR$ or the *ERROR data variable.

  12. If the EOS flag is set, the error variable is too small to contain all of the error information and some error information has been truncated.

  13. The MAILSEND instruction is supported by the Sunbelt Data Manager.

 

When the *SUNDM keyword is being used, the parameters for the MAILSEND instruction have been enhanced to support two tags specified as '<e>' or '<f>'. The '<e>' tag specifies an environment variable name that exists in the SUNDM CFG file that contains the data to be used for the MAILSEND parameter. The '<f>' tag specifies a name for a file located at the Data Manager that contains the data to be used for a given MAILSEND keyword. The support for these embedded tags have been implemented to maximize the configurability of the MAILSEND operations when using the Data Manager. When the '<e>' or '<f>' tags are used, they must be specified as the first data in keyword data string.

Note the following:

  1. The '<e>' tag must be followed by a keyname that is appended to a prefix named 'MAIL_'. A full keyword named 'MAIL_keyname' finds the keyword in the SUNDM CFG file. The data specified by the 'MAIL_keyname' keyword is retrieved and used for the given MAILSEND parameter that includes the '<e>keyname' tag. The 'MAIL_keyname' keywords must be placed in the 'environment' section of the SUNDM CFG file.

  2. The '<f>' tag must be followed by a name that identifies a file whose data is to be read and substituted for the MAILSEND parameter that includes the '<f>filename' tag. The filename supports the normal PLB $Macro and Datapoint style name formats the same as a PLB OPEN instruction. The file identified by the filename must be located at the Data Manager server.

  3. The '<e>' or '<f>' tag substitution can be used for any of the MAILSEND parameters that have a {svarslit} parameter data type.

 

 

See Also: Example Code, System Interface Instructions

 


PL/B Language Reference LOADPARM MOVEADDR