Pseudo-Variables (not added to generated FS files)

The sender and recipient templates may contain pseudo-variables defined using the $var_def command. The following pseudo variables are available:

VariableValue
SMTP_OPTIONSString of character flags:
11 -  drop email body from fax
0 -  use configured option
21 -  disable attached cover sheet
0 -  allow attached cover sheet
31 -  save message header to variables
0 -  do not save message headers
41 -  disable fax from this sender
0 -  allow fax from this sender
51 -  sender must be valid for recipient
0 -  sender need not be valid
61 -  allow scripts in email message body
0 -  remove scripts from email message body
71 -  fax rich content of email body
0 -  use configured option
81 – fax plain text of email body
0 – use configured option
91 – use plain text of email body in memo
0 – use configured option
101 – no cover sheet
0 – use specified cover sheet
111 – create TSV recipient list
0 – do not create TSV recipient list
121 – create CSV recipient list
0 – do not create CSV recipient list
131 – exclude CC fax recipients
0 – include CC fax recipients
141 – exclude BCC fax recipients
0 – include BCC fax recipients
151 – include email recipients in list
0 – do not include email recipients in list
161 – match and use only envelope recipient
0 – use all recipients
171 - only accept TLS e-mail
0 - allow unsecured e-mail
SMTP_PASSWORDPassword (must appear in subject)
SMTP_NOTIFY_OPTIONSString of character flags for notification:

11 -  notify sender on successful fax
0 -  do not notify sender on successful fax

21 -  notify sender of failed fax
0 -  do not notify sender on failed fax

Pseudo-variables do not appear in the FS files generated by the SMTP gateway. They are merely used to control some aspect of processing the message. These variables are not required in the sender or recipient templates. They are only used to override default processing. For example, all of the SMTP_OPTION flags are assumed to be zero, which corresponds to the default or configured behavior for the gateway. You only need to specify as many of the flags up to and including the last flag that you need to set. You should enclose the flags in double quotes to avoid confusion with numeric values. If you do not specify a SMTP_PASSWORD then no password is required, which is the default action. The presence of the SMTP_NOTIFY_OPTIONS pseudo-variable indicates that the global notification settings for the gateway are to be ignored for this sender and the settings specified by SMTP_NOTIFY_OPTIONS are to be used instead. These pseudo variables may be entered directly into the sender template files or you may set them using the options menu selection for sender templates.

You may wish to specify that the email body be dropped if you wish to only fax the attachments of an email message. Dropping the email body only removes it from the list of faxed documents. The email body is still saved as a plain text file so that you can reference it in custom processing if desired. If the rich content of the email message is going to be faxed, it is first processed to remove scripts and to process embedded or inline attachments. Embedded attachments are never faxed separately, but are processed along with the HTML message body by the document converter to create a single document that includes the embedded attachments. The converted document gets faxed. If the plain text of the message body is faxed instead of the rich content the email body will not be processed then it is possible that some inline attachments may be faxed as attachments. The option to disable attached cover sheets prevents the sender from sending an attached cover sheet to override the cover sheet options for the message. If the sender does send an attached cover sheet when this option is set, it is dropped from the attachment list and ignored. If you do not want to have a cover sheet for a particular sender and you have specified a default cover sheet then you must set the no cover sheet option.

The email message body options are mutually exclusive. The SMTP_OPTIONS are processed from left to right. Each email body option (1, 7, 8, and 9) that is set disables the other email body options. If an email message only contains either a plain text message body or a rich content body, such as HTML, then the email body will be faxed using that format regardless of the setting of the fax rich content or fax plain text content options. When the drop email body option is set, then the plain text of the email body is saved to a file if the plain text is available. Otherwise the rich content is saved.

Variables (added to generated FS files)

The SMTP gateway also creates an additional set of variables that may be used in processing the message, either as a fax pre-process, fax post-process, or in a script attached to a worker box. The following additional variables are defined:

VariableValue
FC_NOTIFY_EMAILfirst reply to address for notification
FC_NOTIFY_OPTIONSnotification flags (success/fail/000010)
MEMO#message body text lines
NOTIFY_SENDERemail address notifications sent from
SMTP_ACTUAL_RECIPIENTmailbox used for wild card recipient
SMTP_ATTACH_COUNTnumber of attachments
SMTP_ATTACHFOLDER folder where attachments are stored
SMTP_ATTACHFILE#attachment file name (# - sequence). Deprecated, do not use.
SMTP_ATTACHNAME#original name of attachment (# - sequence). Deprecated, do not use.
SMTP_ATTFILE##attachment file name (## - sequence)
SMTP_ATTNAME##original name of attachment (## - sequence)
SMTP_BODYNAMEfile containing email message body
SMTP_COVERname of cover sheet file (worker box files)
SMTP_FROMmessage from (name <email address>)
SMTP_GLOBAL_LISTFOLDERsystem default recipient list folder
SMTP_HEADER#saved message header data (# - sequence)
SMTP_HEADER_COUNTnumber of saved message headers
SMTP_LIST_FOLDERrecipient list folder used
SMTP_LIST_NAMEname of recipient list file
SMTP_MEMO_COUNTnumber of MEMO variables, if any
SMTP_MESSAGE_PRIORITYmessage priority (0 – 4, highest to lowest)
SMTP_MESSAGE_QUEUETOSEND queue used for FS file
SMTP_MSGBASE8-digit base name of message files
SMTP_MSGFOLDERfolder where message files written
SMTP_MSGIDmessage ID (if present)
SMTP_RCV_DATEdate message received (MM/DD/YYYY)
SMTP_RCV_TIMEtime message received (HH:MM:SS)
SMTP_RECIPIENTmailbox portion of recipient email address
SMTP_REPLYTOmessage reply to list
SMTP_SENDER_EMAILsender email address
SMTP_SENDER_FOUNDTrue/False if matching sender template
SMTP_SENDER_TEMPLATEsender template file (if valid sender)
SMTP_SENT_DATEdate message sent (MM/DD/YYYY)
SMTP_SENT_TIMEtime message sent (HH:MM:SS)
SMTP_SENTTOfull recipient email address
SMTP_SUBJECTmessage subject (excluding password)
SMTP_USED_TLSmessage was received with TLS
SMTP_VALID_SENDERTrue/False if sender validated

 

SMTP_DECODE_RESULTError or warning code from S/MIME decoding
SMTP_DECODE_ERRTEXTError or warning text from S/MIME decoding
SMTP_SMIME_RESULTStatus of incoming message (signed, encrypted, both)
SMTP_DKIM_RESULTError or warning code from DKIM verification

 

Note that SMTP_RECIPIENT includes the name or mailbox portion of the recipient email address only. Typically this is the fax number. However, it may be the name of one of the special recipient mailboxes that have been set up on the system. The gateway always checks for a special recipient mailbox address first before attempting to extract a fax number from the recipient address. Alphanumeric mailbox names must have corresponding recipient templates. However, numeric mailbox names will always be accepted. This means that you can set up dummy fax numbers to perform special processing using recipient templates. Keep in mind that you can still use sender templates for validation, including password checking and options even if you are sending to a special recipient. However, only the FS file commands from the recipient template will be used in the worker box FS file that is generated by the gateway. If the recipient template specifies a password, it must also be in the subject.

The message headers saved to SMTP_HEADER# variables consist of entries in the format:

 Name: Value

where name is the field name for the header (followed by a colon and a space) and value is the actual string content for the header field. Header fields may span multiple lines, which could cause problems in an FS file. When the gateway saves header variables, it first attempts to save the entire header value in a single variable. If the length of that variable exceeds 256 characters then the gateway breaks the header value into separate lines using the line breaks from the original message. Each line is then saved in a separate variable. If any individual line still exceeds 256 characters then only the first 256 characters are saved followed by a … <header line truncated> message.  The header field names are always included at the start of each header variable value, even if the variable contains a continuation line from a previous header variable. Since a single header field may span several header variables, it is a good idea to check for all possible matches on header field name values when trying to reconstruct the original header field value.

The SMTP_BODYNAME variable will not be present if you set the option to drop the email body. The SMTP_HEADER_COUNT variable will only be present if you set the option to save message headers. Messages headers are saved to SMTP_HEADER# variables where # is a sequence number from one to the number of message headers.

The email message body is saved to a file name formatted as follows:

 nnnnnnnn000.xxx

where nnnnnnnn is the FS file number with leading zeroes and 000 is the attachment sequence number, and xxx is the message body file extension, usually htm or txt. The attachments are saved to files using the same naming convention with the attachment sequence number starting at 001. Embedded attachments are saved along with external message attachments. The SMTP_ATTACHNAME# and SMTP_ATTACHFILE# variables define the original name and the fully qualified path name of the saved external attachments. The # portion of the name is a sequence number starting with one through the number of attachments stored in SMTP_ATTACH_COUNT.

Email message parts are not automatically deleted as messages are processed. This allows you to archive them or to retain them for other purposes. The system comes with utilities to scan folders and remove specified files that are older than the than the date you provide to the utility. You may also use the $delete_option in your sender templates to remove files automatically. This command will not remove any embedded attachment files, however, since these files are not named explicitly in any FS file commands. You may add your own post-processing commands to handle the email message parts automatically if you wish.

The SMTP_SENDER_FOUND variable is set to True if a matching sender or default domain template was found for the sender. Otherwise it is set to false. The variable SMTP_VALID_SENDER is set to True if the sender was validated or False if not. A sender will always be validated if you have a global default sender template name. The full path name of the sender template is stored in the SMTP_SENDER_TEMPLATE variable.

The SMTP_MSGBASE variable contains the 8-digit base name of the file that contains the email message. The SMTP_MSGFOLDER variable names the folder where message files are saved and where message information files are written for each message. The message information files contain "envelope" information for the message. These files have a file extension of .MIF. Message files originally have a file extension of .MSG and are changed to .BAK when they are saved after processing. The message information files contain additional information that may be useful for custom applications.

The SMTP_ACTUAL_RECIPIENT variable is only present when an email is processed by a recipient template set up to handle wildcard mailbox names. It will contain the name of the recipient template used to handle the email. The SMTP_RECIPIENT variable will still contain the mailbox portion of the original recipient address. So if you have a recipient template named bcmail and it is set up to handle email addressed to bc*@yourdomain.com and the gateway receives an email sent to bc10993@yourdomain.com then SMTP_RECIPIENT will contain the value bc10993 and SMTP_ACTUAL_RECIPIENT will contain the value bcmail.

Wildcard mailbox processing is ideal for automating the handling of responses from your email broadcast campaigns. By specifying a unique reply-to address for each email you send out, you can uniquely identify the original recipient and the original email should you happen to receive an undeliverable message or any kind of response to the email. You can then use the response to automatically update your broadcast lists and campaign databases. The use of a unique reply-to address means that you do not need to depend on recognizing the sender to identify the original email and the recipient of that email. This allows you to handle bouncebacks sent by the system administrator, as well as responses from forwarded email. And you don’t have to create a unique recipient template for each possible response.

SMTP_DECODE_RESULT values

This variable provides the result of the verification and decryption process and can have the following values:

0No errors or warnings
<0Message verification/encryption failed

 

-27Buffer for decrypted message too small
-28Assemble message after decryption failed
-30Parse message failed
-31Decryption Certificate file not found or not read
-34Decryption Certificate not loaded
-35Decryption Certificate has no e-mail address

 

-36Verification Certificate file not found or not read
-37Verification Certificate not loaded
-38Verification Certificate has no e-mail address

-39Message format error
-40Decode Failure
-41Decode Exception
-42Unknown message handler
-43Decode error/warning

For code -43, one or more of the following will be recorded in the SMTP_DECODE_TEXT variable:

Unknown, SignaturePartNotFound, BodyPartNotFound, InvalidSignature, SigningCertificateMismatch,  EncryptingCertificateMismatch, NoData, InvalidMessageDigest,  OmittedMessageDigest.

SMTP_SMIME_RESULT values

This variable provides the status of the incoming message and can have the following values:

-1Message could not be analyzed
0Message is not signed or encrypted
1Message is signed
2Message is encrypted
3Message is signed and encrypted

Note that a positive value in this variable does not imply that the message has been successfully verified or decrypted.

SMTP_DKIM_RESULT values

This variable provides the result of the DKIM verification process and can have the following values:

-1DKIM verification was not done (verifyDKIM keyword not supplied on $email_security

 

0DKIM successfully verified

 

1Verifier not in correct state
2Verifier detected invalid header
3Verifier found no address
4Verifier found no signature
5Verifier found invalid format
6Verifier found unknown algorithm
7Verifier error
8Domain mismatch
9Invalid timestamp
10Signature expired

 

101Failed to look up TXT record in sender domain DNS records

 

201No DKIM data found in DNS
202No DKIM parameters found in DNS
203No DKIM key found in DNS
204Invalid DKIM key type
205Invalid DKIM key data

 

302Bad key
303No key
304Key revoked
305No signature
306Bad format
307Not DKIM participant
308Unknown error
309 Expired
310 NotExact
311Bad granularity

Errors numbered from 1 to 10 apply to the analysis of the message; the 200 range applies to the records obtained from the sender's DNS records, and the 300 range from analysing everything together.