CopiaFacts™ Reference Manual

This topic describes variables which are written into FS files generated by the Gateway.  For Sender Template variables which control the processing performed for each sender, see the SMTP Sender Options topic.

Variables added to generated FS files

The SMTP gateway also creates and adds to FS files 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.

It is important to note that these variables are effectively read-only variables. COPIAFACTS does not use them, and setting them yourself will have no effect on CopiaFacts processing; they simply report what has been configured or what has happened, and can be used in custom scripting, reporting or analysis.

The following additional variables are defined:

 

 

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.

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, but line breaks are replaced by spaces in the variable value. The SMTP_HEADER_COUNT variable will only be present if you set the option to save message headers.

The SMTP_BODYNAME variable will not be present if you set the sender option to drop the email body.

The email message body is saved to a file name formatted as 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 01. Embedded attachments are saved along with external message attachments. The SMTP_ATTNAME## and SMTP_ATTFILE## 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. You can use CFHK to scan folders and remove or archive specified files that are older than the than the date you provide to the utility. You can 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.

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

If decodeSMIME was specified in $email_security and the message was signed or encrypted (see SMTP_SMIME_RESULT below) this variable provides the result of the verification and/or decryption process and can have the following values:

For some codes, the trace may show a specific 4- or 5-digit error number beginning with 7; for a list of possible codes see the Secure E-Mail Certificate Errors topic.

For codes -42 and -43, one or more of the following will be recorded in the SMTP_DECODE_ERRTEXT variable and in the Gateway trace file:

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

For codes -39, -40, -41, -43 and -44 the processing of the message will have failed.

SMTP_SMIME_RESULT values

If decodeSMIME was specified in $email_security this variable provides the status of the incoming message and can have the following values:

Note that a positive value in this variable does not imply that the message has been successfully verified or decrypted.  You should check SMTP_DECODE_RESULT above to see if the signature was verified or the message was decrypted.

SMTP_DKIM_RESULT values

If verifyDKIM was specified in $email_security this variable provides the result of the DKIM verification process and can have the following values:

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 analyzing everything together.