APSMail sends mail as defined by an email template file. Everything that APSMail needs to know to construct and send the message can be defined within the template.
Template files are simple ASCII text files; they require no specific editor or tools to operate on. Text lines may be terminated with either carriage-return/linefeed pairs or merely linefeeds (so the differences between Windows and UNIX are not significant).
A template file contains the body of the message to send, along with directives that control how the message is sent and related operations. In addition, embedded within the text can be references to macros and lookups.
Each email template file should contain all of the information required to send the file. Some settings may or may not be required by your mail server.
As each line is read from the file, the line is examined to see if it certain text must be replaced with other text ("macros" or "lookups"). After replacement, if a line in the file begins with one of the directives described in the following sections, it will not be used as part of the message body and the text following the keyword will be used as described. Note that replacements references (macros and attributes) are replaced in these lines.
Everything else is considered part of the message body.
Replacement macros and attributes are also supported in file names, though a UNIX site must be very careful with case sensitivity in file names. This can be useful for supporting multiple languages or special mails by user type.
Macros are named values. That is, a name represents a value that is determined at a later time or in a different place.
APSMail allows the use of three different kinds of macros: Application, Define and Environment variables.
A macro reference may appear anywhere in the email template file or in a template file name or path. Before processing a file name or path, any macro references contained within the path are replaced with their value. Similarly, as each line is read in from a template file, any macro references are replaced with their current value.
Application macros are defined by the calling application and are usually context specific. For example, when sending Password Expiration Warning email, APS exposes a DaysLeft macro so that the email can contain the number of days before the password actually expires. See the application's documentation to determine what application macros are available in each context.
Application macros can be referenced in three ways: as %<macro name>%, {macro: <macro name>} or as {%<macro name>}. All are equivalent, but the first form is deprecated and is being phased out.
Using the prior example, in an APS Password Expiration Warning email, the text might read:
Your password will expire in {%DaysLeft} day(s). Please change it before that time.
Macros can also be defined within the template files themselves using the [DEFINE] directive (discussed later in this chapter). This is typically used with the [INCLUDE] statement to specify settings.
Define macros are referenced in exactly the same way as application macros.
[DEFINE SMTPServer] 127.0.0.1
[MAIL SERVER] {%SMTPServer}
Environment variables can also be referenced within an email template file. The syntax is very slightly different. Instead of a percent sign ("%"), use a dollar sign ("$").
[MAIL SERVER] {$OUR_MAIL_SERVER}
Several alternate formats can be used for referencing environment variables. All of the following are also supported, but not recommended (the second form is deprecated).
[MAIL SERVER] {env: OUR_MAIL_SERVER}
[MAIL SERVER] %ENV_OUR_MAIL_SERVER%
APSMail also supports Lookups. When APSMail encounters a lookup, it calls back into APS to get a value for the lookup. This is typically done to retrieve values from the user record.
Note that lookups are supported by the APS, not APSMail directly.
Lookups are referenced within curly braces. There are two forms:
{<attribute>}
This form generally represents a raw data field from the default user record. For example, {cn} would typically be replaced with the value of the cn attribute of the user.
Another form of a lookup reference is
{<qualifier>:<attribute>}
This form has specific, application-defined uses. For example, if there is more than one user involved, an application might have a qualifier of "Administrator", in which case "Administrator:cn" refers to the common name of the administrator instead of the common name of the user.
APS docs not currently support any qualifiers.
In most cases, if the first form of lookup is supported, you can use the well known SiteMinder attributes as well as attributes that reside in the user directory itself.
The Well Known attributes are documented in the SiteMinder manuals and include such things as the user's IP address (only useful if sending mail while a user is currently online).
The email template file contains directives that tell APSMail how to send the message. Each directive appears on a single line and must start at the beginning of the line. The entire line is considered part of the directive and will not be included in the message body. Anything that is not a directive will be included in the message body.
All directives are surrounded by square brackets ("[" and "]") and start at the beginning of the line. Directives may appear anywhere in the file, but the file is only processed once, so directives that have an effect on file processing will only affect from the point where they appear in the file.
Some directives may appear more than twice and will be processed for each appearance (such as the ATTACH directives). Other directives should only appear once; if such a directive appears more than once, the last instance will be used.
A directive can reference macros and lookups.
Example:
[INCLUDE] <path>
The Include directive tells APSMail to include the file specified and process its contents as though it appeared at that same point in the original template. Included files may include other files, but APSMail will detect if the same file is included recursively and will issue an error.
The <path> is not processed in any way (the search paths are not used), it is merely opened directly. Most systems should use an environment variable (as a macro) to identify the location of this file.
[INCLUDE] {$MASTER_MAILFILE}master.etf
Example:
[DEFINE <name>] <value>
This directive allows a site to create definitions of symbols (<name>) representing a value (<value>). If <name> is represented elsewhere in the file (below the point where the [DEFINE] directive appears), the reference is replaced with the value. For more information, see Define Macros.
Lookups can be used in Macro definitions.
Macros are only "visible" from the point at which they are defined.
Example:
[COMMENT] <text> [REMARK] <text> [REM] <text>
Any line containing this directive is completely ignored. It is useful for placing comments into the template file to ease maintenance or to temporarily disable other directives in the file.
[REM] Last updated by John Smith on 4/1/2003 [REM] Test sending synchronously - [ASYNCHRONOUS]
Example:
[LOGPATH] <path> [LOG PATH] <path>
This directive specifies a path where the result of this send should be logged. This overrides both the application and environment variables. It is not often used. It might be used, however, if different templates are to be logged to different files.
Example:
[MAILSERVER] <server> [MAIL SERVER] <server> [SMTPSERVER] <server> [SMTP SERVER] <server> [SERVER] <server>
This directive overrides both the environment variable and any application-specified mail server to tell APSMail where to find the SMTP server. If no SMTP server is specified, then no message will be sent.
This directive is frequently used in a centrally included template file.The <server> may be specified as an internet machine name or an IP address. It may also be followed by the port to use, separated from the server address by a colon, as in smtp.acme.com:50 or 127.0.0.1:50. It is very unusual to use a port other than the default SMTP port.
Example:
[TIMEOUT] <seconds>
This directive specifies the amount of time to wait for mail server responses. By default, APSMail will wait up to 30 seconds for a response from a mail server. This value must not be zero.
Shorter values do not improve performance in any way.
If this value is too low, it may cause APSMail to prematurely decide that a server is not responding and will result in errors. If too high, real errors from the server will not be detected for some time.
[TIMEOUT] 60
Example:
[LOCALHOST] <hostname> [LOCAL HOST] <hostname> [STATION] <hostname> [HELLO] <hostname> [HELO] <hostname> [EHLO] <hostname>
This directive specifies the name to use on the mail server greeting message. Per the SMPT RFC, this should be the name of the local host. If not specified, APSMail will look up the name of the local host. This can also be specified in an environment variable, but any value appearing in this directive will override an environment setting.
SMTP supports a single security option. ESMTP requires the MAIL FROM command (like SMTP), but also provides two other alternatives for security. At this time, APSMail does not support these additional security options. If the SMTP service is local to the APSMail service, these options are not needed.
Example:
[MAILFROM] <email address> [MAIL FROM] <email address>
This directive specifies the email address to send to the mail server in the MAIL FROM command. All servers require MAIL FROM. Some require that the address be known to the server or that the address be in the same internet domain as the server.
The value used for MAIL FROM can come from a variety of places if not specified in an explicit directive. The APSMAIL_LOGIN environment variable will be used if this value is not set.
If it is not explicitly set by the environment variabl and this directive does not appear, then the value from the SENDER or FROM directives will be used.
[MAIL FROM] administrator@acme.com
Example:
[FROM] <email specifier>
This directive specifies the FROM address of the message. If not set, the SENDER will be used. This value is used in the FROM header of the message. If different from the SENDER, some email clients will show one or the other or a combination of both the FROM and SENDER headers.
This is supposed to be (according to the RFC) only used to display who the message was from. However, its misuse has caused some email clients to perform special processing, if different.
The <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
Example:
[SENDER] <email specifier>
This directive specifies the address of the sender of the message. If not set, the FROM address will be used. This value is used in the SENDER header of the message. If different from the FROM, some email clients will show one or the other or a combination of both the FROM and SENDER headers.
This is supposed to be (according to the RFC) used to record who the actual sender was, for purposes of error handling and replies. However, its misuse has caused some email clients to perform special processing, if different.
The <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
Example:
[SUBJECT] <text> [RE] <text>
This directive tells APSMail the subject line to use for this message.
[SUBJECT] Your password will expire in {%DaysLeft} day(s)
Example:
[TO] <email specifier(s)>
This directive tells APSMail who to send the message to directly (as opposed to copies). More than one address can be specified, separated by semi-colons.
These addresses are used in the TO header of the message as well.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com
[TO] {mail};{pagermail}
Example:
[CC] <email specifier(s)>
This directive tells APSMail who to send copies of the message to. More than one address can be specified, separated by semi-colons.
These addresses are used in the CC header of the message as well, so they are visible to all message recipients.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com [CC] helpdesk@mycompany.com
Example:
[BCC] <email specifier(s)>
This directive tells APSMail who to send copies of the message to. More than one address can be specified, separated by semi-colons.
These addresses are not visible to message recipients.
Each <email specifier> can be just an internet email address or can be something like:
"John Doe" jdoe@acme.com [BCC] audit@mycompany.com
Example:
[REPLYTO] <email address> [REPLY TO] <email address >
This directive sets the REPLY-TO header in the message. If a reply is sent to the message, the reply is to go to this address instead of to the sender.
The <email address> should be an internet email address.
[REPLY TO] helpdesk@mycompany.com
Example:
[ERRORSTO] <email specifier> [ERRORS TO] <email specifier>
This directive sets the ERRORS-TO header in the message. Some mail servers will use the email address specified in this header to send delivery error messages to. If this directive is not specified, errors are sent to the sender or reply-to address.
The <email address> should be an internet email address.
[ERRORS TO] helpdesk@mycompany.com
Example:
[RETURNRECEIPT] <email address> [RETURN RECEIPT] <email address> [RETURNRECEIPTTO] <email address> [RETURN RECEIPT TO] <email address>
This directive specifies that read receipts are requested from each of the recipients of the message. Read receipts are only expected to be sent when the message is marked as read by the user of that client.
There is no guarantee that the client program will actually send such a receipt. Email clients can usually be configured to suppress, prompt or automatically return such a receipt. This directive therefore can only request such a receipt.
The <email address> is optional. If not included, then no specific address will be included with the message and any return receipt, if sent, will be sent to the sender of the message. It should be just an internet address, not a full email specifier.
[RETURN RECEIPT] audit@mycompany.com
Example:
[DISPOSITION] <email address> [DISPOSITIONNOTIFICATION] <email address> [DISPOSITION NOTIFICATION] <email address> [NOTIFICATION] <email address> [DISPOSITIONTO] <email address> [DISPOSITIONNOTIFICATIONTO] <email address> [NOTIFICATIONTO] <email address> [DISPOSITION TO] <email address> [DISPOSITION NOTIFICATION TO] <email address> [NOTIFICATION TO] <email address> [NOTIFY] <email address>
This directive specifies that delivery receipts are requested from each of the recipients of the message. Delivery receipts are usually sent by the email SERVER that delivers the message to the email client. While servers can be configured as to whether they return these receipts or not, it is more likely that such a request be honored.
There is still no guarantee that such a receipt will actually be sent. This directive therefore can only request such a receipt.
The <email address> is optional. If not included, then no specific address will be included with the message and any receipt, if sent, will be sent to the sender of the message. It should be just an internet address, not a full email specifier.
[NOTIFY] audit@mycompany.com
Example:
[ORGANIZATION] <text>
This directive sets the ORGANIZATION header in the message. This is a relatively new header in the SMTP specification. Most clients just display its contents.
[ORGANIZATION] Acme, Inc.
Example:
[PRIORITY] LOW [PRIORITY] LO [PRIORITY] NORMAL [PRIORITY] NORM [PRIORITY] HIGH [PRIORITY] HI
This directive sets the message priority. This has little to do with message handling at any point in the delivery of the message. It is typically used by the email client reading the message to determine how to display it.
[PRIORITY] HIGH
Example:
[TEXTMODE] PLAIN [TEXTMODE] ENRICHED [TEXTMODE] HTML
This directive tells APSMail the format of the message body. APSMail will encode the body as required by this directive and set the MIME type of the message accordingly. If this directive is not specified, PLAIN is assumed.
APSMail is not involved with the formatting of the message body, this setting merely tells the system what MIME type to use. The development of mail content using ENRICHED or HTML formatting is completely up to the site.
Example:
[CHARSET] <ISO-character-set-identifier>
This directive tells APSMail what character set to associate with the message body and to use for plain text character quotation. By default, ISO-8859-1 is used.
APSMail does no edit checking on this value.
Example:
[X-<name>] <value>
The Electronic Mail Format specification allows for extensions to the message headers in the form of what are called X-Headers. These headers are in the form of X- + <some name text> + ":" + <some value>. If a client does not know how to process such a header, it is merely carried along and ignored.
APSMail automatically inserts a single X-header, called X-Mailer, which identifies the version of APSMail used to generate the message.
Additional custom headers can be included in the message as well using this directive. Header names in this context are case-sensitive.
A blank <value> will suppress a particular header, so, for example,
[X-Mailer]
will suppress the sending of the APSMail header.
Anything not on a directive line contained in a template file (or included template files) will be added to the message body. This includes blank lines!
|
Copyright © 2014 CA.
All rights reserved.
|
|