Specify E-Mail Address
$email_address address_element [address_element ...]
This command specifies the address to be used for an e-mail broadcast item. When this command is used, the $fax_phone and $voice_phone commands are normally omitted from the FS file.
Each e-mail FS file results in a transmission to a single recipient. However it is possible to send CopiaFacts e-mail which appears to each recipient to have been sent to other people also. The basic (manual) method of doing this is to set the variables EMAILTO_LIST or EMAILCC_LIST to with values containing one or more e-mail addresses; these variables can also be set automatically from Job Administration broadcast lists. See the topic Sending E-Mail to Multiple Recipients for more information. This command also does not support e-mail address groups.
If both this command and a fax or voice phone command is given, then both methods of transmission will be attempted in turn. If $email_options "second" is given, then the e-mail will be tried only if the fax/voice outbound operation fails. Otherwise, the e-mail will be attempted first and only if it fails will the fax/voice operation be tried. This feature would allow an e-mailed WAV file to replace a voice outbound call, or an e-mailed DOC attachment to replace a faxed document converted to faxable TIFF.
The parameter on this command is used as follows:
| address-element | components of a single e-mail address in the format described below |
The default macro-expansion character on all $email... commands is an ASCII grave accent character (`).
The supplied address parts are combined on the e-mail 'To:' header, separated by space characters. Double-quote characters have no special significance and are passed to the e-mail header line exactly "as-is". For compatibility with earlier releases, double-quote characters may also be preceded by the macro-expansion character (default `).
A typical e-mail address consists of an optional double-quoted display-name, an address-part, and an optional comment in parentheses. Angle-brackets should be placed round the address part when a display name or a comment is present. The address part consists of a local name (also known as the mailbox) and a domain name, separated by an @-sign. The full address string should conform to RFC 5322. Note that international e-mail addresses (RFC 6531) are not currently supported.
CopiaFacts needs to extract only the address-part to use on the SMTP command RCPT TO, and will use the full address on the To: header inside the e-mail itself.
The address on this command can be parsed in two different ways, depending on whether the $email_options keyword sanitize is used.
Standard E-Mail address handling
The default method of extracting an e-mail address-part from the supplied destination address is used when the $email_options keyword sanitize is not used. This is suitable for applications where the e-mail addresses can be assumed to be well-formed, such as for internal staff addresses derived from Active Directory in a fax-to-email application; or for address lists known to be 'undecorated', without comment and display-name parts. The parsing to find the address-part is done as follows:
•If the whole address is enclosed in double-quotes (deprecated) and has no embedded double-quotes, the enclosing double-quotes are removed.
•Any address element enclosed in angle-brackets is extracted as the address-part for the SMTP command, and the remainder is ignored.
•Address elements enclosed in double-quotes (the display-name) or in parentheses (the comment) are removed
•The remainder is treated as the address-part (mailbox@domain)
When the default method of handling e-mail destinations is use, the supplied address is always used unchanged on the To: header inside the e-mail, and only the extracted address-part is used on the RCPT TO command
Where destination e-mail addresses are not under your control, you can use the $email_options keyword sanitize to correct some of the incorrect syntax. Note that adding this option will result in some rejections (outcome code 194), if an e-mail address is ambiguous or is not correctable. However not using it may also result in some e-mails being sent but not delivered. The parsing, checking and editing is done as follows:
•If the whole address is enclosed in double-quotes (deprecated), they are removed. In case embedded double-quote characters have been duplicated as a result of the double-quoting, any pairs of double-quoted characters are also converted to a single double-quote character.
•E-mail addresses that are too short to contain all the required syntax elements at any stage in the processing cause a rejection.
•An initial double-quoted string that precedes an e-mail address in angle-brackets is treated as the display name and is temporarily removed from the address. An opening angle bracket in the display name must be escaped as \<; if it is not, the address will be rejected, because it might be caused by a failure to terminate the double-quoting.
•Any words between the display name (or the start of the address if no display name is present) and an angle-bracket which introduces the address part are added to the display name.
•If the address ends with a comment in parentheses, it is treated as the comment and temporarily removed from the address.
•The remaining part of the address is checked: if it starts with an opening angle-bracket but does not end with a closing angle bracket, it is treated as if it had a closing angle bracket at the end. This content then becomes the address-part.
•On validating the address-part, the following syntax errors are identified:
▪No @-sign present
▪Multiple @-signs present
▪Zero-width characters (U00A0, U200B - U200F) are trimmed from each element
▪No domain name following the @-sign
▪Domain name contains .. or starts/ends with .
▪Domain name contains non-ASCII or invalid characters
▪No local name preceding the @-sign
▪Local name consisting of a double-quoted string contains invalid characters
▪Local name contains .. or starts/ends with .
▪Local name contains non-ASCII characters
▪Escape characters (U001B) are retained in quoted strings (for iso-2022-jp encoding)
•If the local name is not double-quoted and contains characters which require double-quoting, double-quotes are added to the local name.
•A new complete e-mail address is built with double-quoted display name (if present), address part (in angle brackets if other parts are present), and comment (if present).
When the 'sanitize' method of handling e-mail destinations is use, the supplied address is replaced on the To: header inside the e-mail with the new complete address fully compliant with RFC 5322, and only the extracted address-part is used on the RCPT TO command. The address in the SENT FS file is not updated with a modified address.
When the sanitize process corrects a syntax error it will be reported in the CF9EMAIL trace output to FFTRACE. Minor changes in spacing will not be reported. Syntax errors which cannot be corrected will result in outcome code 194 and no e-mail will be sent.
Default: none (required command for e-mail)
Examples:
$email_address steve@copia.com
$email_address "Steve Hersee" <steve@copia.com>
$email_address <steve@copia.com> (Steve Hersee)
$email_address "`BCF2" <`BCF1>
$email_address <"steve"@copia.com>
$email_address "steve@copia.com" ; deprecated
$email_address steve@copia.com <steve@copia.com> ; deprecated
See also these examples for sending to CC and BCC recipients.
