Sending Email From a Procedure

How to:

Use EX EDAMAIL in the Positional Parameter Form
Use EX EDAMAIL in the Extended Form

Reference:

Configuring SMTP Server Parameters

EDAMAIL is an internal procedure that allows you to send emails from a procedure with the content of a specific file included in the email body or as an attachment. This is useful for sending email alerts for events ranging from special error conditions to simple report completion. EDAMAIL requires a configured (and working) email SMTP Server node.

There are two forms of syntax for EDAMAIL:

The original form uses positional parameters, and is limited to the original specification.
The extended form uses non-positional, name-value pair parameters. The extended form supports additional SMTP email client features such as Reply To and Importance.

The extended form is assumed if the first parameter contains an equal sign (=) indicating that a name-value pair is being passed.

Most forms of email addresses are acceptable, including support@ibi.com, support1 <support@ibi.com>, and "support1" <support@ibi.com>. A semi-colon is used as the address separator for parameters that allow multiple email addresses. A comma is also allowed as a separator if the overall address string is enclosed in single quotation marks.

The actual use and display of the email headers created by EDAMAIL are a function of the SMTP Server in use (and any intervening SMTP hops), plus the user email client (such as Outlook, Gmail, Hotmail, and so on). They are not directly controlled by the sender email headers. Therefore, an email may not always exhibit the expected behavior in all email client environments. For example, older email clients may not recognize newer header types, and may ignore Reply To. Any functional issues should first be investigated by an experienced SMTP/Email administrator to determine if they are client-related.

Reference: Configuring SMTP Server Parameters

You must configure the SMTP Server node in the odin.cfg file. This configuration file is in the etc directory:

install_dir/ibi/srv77/foc/home/etc

The following declarations configure the SMTP Server node.

;SMTP mail server client
NODE = EMAIL
BEGIN
  SMTP_HOST = host
  PORT = port
  SENDER_EMAIL = email
  PROTOCOL = SMTP
  CLASS = SMTPCLIENT
END

where:

host: Is the domain name of the SMTP Server.
port: Is the port on which the SMTP Server is listening.
email: Is the sender email address for automatic emails.

Syntax: How to Use EX EDAMAIL in the Positional Parameter Form

The syntax is:

EX EDAMAIL to, from, subject, [flag], filetype, data

where:

to

Is the email recipient. Multiple addresses are allowed, using a semi-colon as the address separator.

from

Is the email sender.

subject

Is the email subject string. If the subject string contains a comma, the string must be enclosed in single or double quotation marks.

flag

If set to a or A, the file is sent as an attachment. Otherwise, it is included as the body of the email. All other values are ignored. The value is also ignored if the filetype parameter is blank.

filetype

Defines the data file type for an email message body that uses a file. Any application file type is valid, including MASTER, FOCEXEC, HTML, and TEXT. Leave the parameter empty to use the inline email message body feature.

data

Is the inline data stream for the email message body or the [app/]filename file containing the email message body. The inline data stream feature requires an empty filetype parameter. The EDAMAIL feature can also spread an inline email message body onto multiple lines using the -LINES {n|*} feature.

If an inline data stream message body is spread across multiple lines in the procedure, the resulting email is a single line of output. Multi-line message bodies are respected when the message body from a file option is used.

Example: Mailing an HTML File as Message Body

TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL  user1@corp1.com, user2@corp1.com, File1 Report,,HTML, MYFILE

Example: Mailing an HTML File as a Message Attachment

TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL  user1@corp1.com, user2@corp1.com, File1 Report,a,HTML, MYFILE

Example: Mailing a Multi-Line Inline Message

...
EX -LINES * EDAMAIL user1@corp1.com, user2@corp1.com, &SUBJECT,,, 
    Run result for &TESTNAME is:
&RESULT
EDAMAIL*

Syntax: How to Use EX EDAMAIL in the Extended Form

The EDAMAIL extended form using name-value pairs is activated by the detection of an equal sign (=) in the first parameter. Parameter names are not case sensitive and may be in any order, but the message parameter (if used) must be last.

The syntax is:

EX EDAMAIL to=addresslist, [toaddr=addresslist,] [from=address,]
 [fromaddr=address,] [replyto=address,] [importance=low|normal|high,]
 [subject=string,] [flags=value,] [filetype=extension,]
 [filename=file,] [message=body message]

where:

to=addresslist

Is the email recipient displayed by the user email client (and used in an email client Reply To All, if a toaddr header is not supplied). Multiple addresses are allowed, using a semi-colon as the address separator. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks.

If the to parameter is used in conjunction with toaddr, the value of to may be an arbitrary string, such as "Group Managers", which most email clients will display as a pseudo-title in the To field without displaying the actual addresses used in the toaddr parameter. A forced blank can be supped for the To field by using to="".

toaddr=addresslist

Is the email recipient. If not supplied, SMTP servers will use the to header. Email clients will use the toaddr value in an email client Reply To All. Multiple addresses are allowed, using a semi-colon as the address separator. A comma is also allowed as a separator, if the overall address string is enclosed in single quotation marks.

from=address

Is the email sender displayed by the email client (and used in an email client Reply, unless overridden by a fromaddr or Reply To header). If the from parameter is used in conjunction with fromaddr, the from value may be an arbitrary string, such as The Boss, which most email clients will display as a pseudo title in the From field, and will not display the actual address used in the fromaddr parameter.

fromaddr=address

Is the email sender. If not supplied, most email clients will use the From header when doing a reply.

replyto=address

Is the email sender. If not supplied, most email clients will use the fromaddr or from parameter value.

importance=low|normal|high

Is the email importance level for email clients that support importance flags. Valid values are high, normal, and low.

subject=string

Is the email subject string. If the subject string contains a comma, the string must be enclosed in single or double quotation marks.

flags=value

If set to a or A, the file is sent as an attachment. Otherwise, it is included as the body of the email.

filetype=extension

Defines the data file type for an email message body that uses a file as the body. Any application file type is valid, including MASTER, FOCEXEC, HTML, TEXT, and so on. Leave the parameter out to use the inline email message body feature.

filename=file

Defines the data file for an email message body that uses a file as the body. Leave the parameter out to use the inline email message body feature.

message=body message

Is the inline data stream containing the email message body. If used, it must be the last parameter in the EDAMAIL command. To use the inline data stream feature, the filetype and filename parameters cannot be supplied. The data stream may also be spread onto multiple lines if EDAMAIL is used with the EX -LINES {n|*} feature.

Example: Mailing an HTML File as a Message Body Using Multiple Addresses and Extended Form

TABLE FILE file1
PRINT A B C
ON TABLE HOLD AS MYFILE FORMAT HTML
END
EX EDAMAIL to=Managers,toaddr=user1@corp1.com;user2@corp1.com,
from=support1@corp1.com,subject=File1 Report, filetype=HTML, 
filename=MYFILE