Manpages

NAME

faxmail - Hyla FAX mail-to-fax gateway application

SYNOPSIS

faxmail [ options ] [ destination [ from ] ]

DESCRIPTION

faxmail takes an electronic mail message on standard input and submits it as a facsimile to a Hyla FAX server for transmission.

faxmail is designed for use in constructing electronic mail to facsimile gateway services. For example, mail aliases may be created to automatically transmit electronic mail; e.g.

sam: "|/usr/bin/faxmail sam@5551212"
or faxmail may be used as a ’’mail transport agent’’, extracting the necessary delivery information directly from the envelope of the mail message.

FORMATTING

faxmail formats a mail message according to the following rules: First it parses the envelope information interpreting any meta-header information (see below) that is present. Once the entire envelope has been collected it emits a formatted set of header lines. By default all header information except the ’’From’’, ’’To’’, ’’Cc’’, ’’Subject’’, and ’’Date’’ lines are discarded. Header lines that are kept have the tag (the string to the left of the ’’:’’) set in a bold font and the value (the string to the right of the ’’:’’) set in an italic font. Mail messages that conform to the Multipurpose Internet Mail Extensions ( MIME ) specification are parsed and handled according to the rules given below. Plain text body parts of a mail message are formatted in a text font with any long lines wrapped at word boundaries unless the -c option has been specified.

By default, faxmail sets all text in 10 point type on an 8.5" by 11" portrait-oriented page with .35" top margin, .25" bottom margin and .25" left and right hand margins. There are command-line options to control the point size, page dimensions, orientation, and multi-column formatting. Text formatting can also be controlled through meta-header directives placed in the envelope of the mail message.

ENVELOPE PROCESSING

faxmail pre-processes the envelope information (i.e. the header lines) before formatting the message contents. Header lines whose names begin with ’’X-FAX-’’ (case-insensitive) are handled specially-they are treated as command directives that specify how to generate the resultant P OST S CRIPT or, optionally, how to deliver the resulting document as facsimile. The set of known meta-headers corresponds to the set of configuration parameters defined below. A meta-header is specified as ’’X-FAX-parameter’’ where parameter is the name of a configuration parameter; e.g. ’’X-FAX-TabStop’’ to set the number of spaces between tab stops.

Controls for specifying headers to be passed through in the formatted text identify not only which headers but also the order in which the headers should be emitted. faxmail initializes the set of headers to retain to: ’’To From Subject Cc Date’’. If this order is acceptable then additional headers can simply be added with the X-FAX-Headers directive; e.g. ’’X-FAX-Headers: Message-id’’. If however a different order is desired then the header set should be cleared with a ’’clear’’ header tag and then completely specified in the desired order; for example,

X-FAX-Headers: clear Message-id Date To Subject From Cc

will cause headers to be emitted in the order ’’Message-Id Date To Subject From Cc’’ (depending on what headers are present). Note in particular that all header lines in the envelope can be suppressed by specifying ’’X-FAX-Headers: clear’’; this is useful, for example, when the body of the mail message contains a preformatted document that is to be transmitted.

In addition to the above controls, faxmail can also be instructed to substitute an arbitrary string for a header tag when generating the final envelope. This facility can be used to better format ad-hoc header information that is passed through the envelope of the message. The ’’X-FAX-MapHeader’’ meta-header specifies how to map a header line. For example,

X-FAX-MapHeader: x_FAX_For Deliver FAX To

would cause any header ’’x_FAX_For’’ that appeared in the envelope to be replaced in the formatted envelope by ’’Deliver FAX To’’.

MIME PROCESSING

faxmail parses MIME mail messages and does some rudimentary work to:

MIME processing is fairly simple and (currently) somewhat constrained. faxmail has builtin support for the following MIME parts: text/plain, multipart/mixed, multipart/digest, message/rfc822, application/postscript, and application/x-faxmail-prolog. Parts can also be processed through external processing scripts that faxmail looks for in a ’’ MIME converters’’ directory hierarchy. External scripts may override builtin processing or suppliment the builtin support. For each MIME body part with type T and subtype S faxmail checks first for an executable script named T/S in the converter hierarchy. If a script exists then it is run and the resulting output is saved as a document submitted to Hyla FAX . If the output is empty, the part is suppressed, and will not be submitted. All other parts will be saved as documents and submitted to Hyla FAX . faxmail uses the typerules(5). mechanism to convert file formats into one of the format Hyla FAX supports.

The builtin handling support is as follows: text/plain parts are formatted using the default text font and point size; multipart/mixed are ’’burst’’ and interpreted per the specification but are otherwise unformatted; multipart/digest are burst and an optional ’’digest divider’’ marking may be inserted before each subpart; message/rfc822 are formatted as described above with envelope header lines culled and formatted with bold and italic fonts (in addition, if there is insufficient space in the current output page/column for the message envelope, optional divider, and one line of text, then faxmail will insert a ’’break’’ so the the message starts at the top of the next page/column); application/postscript are copied through untouched to the output; application/x-faxmail-prolog are copied through untouched to the end of the prologue section of the generated PostScript document to permit customization of the formatted output.

faxmail supports the following Content-Transfer-Encoding schemes: 7bit, 8bit, binary, base64, quoted-printable, and x-uuencode. Any character set that is not us-ascii is treated as iso-8859-1.

SERVER DELIVERY

When faxmail is invoked it delivers the formatted document directly to a Hyla FAX server for transmission as facsimile. Command line arguments may be supplied to specify the delivery destination and sender identity; typically from information extracted by the mail transport facility. A command line destination is specified with the same syntax as the argument for the -d option to the sendfax(1) command. Similarly any from identity specified on the command line follows the same rules as the -f option to sendfax. An explicit dialstring to use in delivery can also be specified with an X-FAX-Dialstring header in the mail message envelope. If no sender identity is provided on the command line then faxmail will extract it from the ’’From’’ line in the envelope. faxmail will not submit a message for delivery if either the dialstring or sender identity is missing or null.

X-FAX- header lines may be included in the mail message envelope to control the submission and delivery process. As above these lines are specified as ’’X-FAX-parameter’’ where parameter is the name of a configuration parameter for the sendfax program; e.g. ’’X-FAX-VRes’’ to set the vertical resolution of the transmitted facsimile. By default automatic cover page generation is enabled when direct delivery is used; this can be overridden with the -n option on the command line or by including an X-FAX-AutoCoverPage header in the message envelope.

OPTIONS

-Ml=#,r=#,t=#,b=#

Set the page margins; the default margins are: left and right .25 inch, top .35 inch, bottom .25 inch.

CONFIGURATION PARAMETERS

faxmail reads configuration information from the files /etc/hylafax/hyla.conf, /etc/hylafax/sendmail.conf, /etc/hylafax/faxmail.conf, and ~/.hylarc; in that order. Configuration files follow the conventions described in hylafax-client(1). In addition to the formatting configuration parameters below, all of the parameters listed in the sendfax(1) man page apply as well.

The following configuration parameters are recognized to support formatting:
Tag Type Default Description

Values marked as inches are specified using a syntax that identifies one of several possible units:

Unit names can be upper or lower case but no white space is permitted between the number and the unit. Values specified with no unit are interpreted as points.

The configuration parameters are explained below. Most parameters correspond to a command line option. Parameter values identified above as inches are converted according to the conventions described above.

NOTES

Because a sender’s identity in an electronic mail message is inherently untrustworthy, using faxmail to build a mail to fax gateway is problematic. Unless mail service is somehow restricted or the sender’s identity is verified using a mechanism such as RFC 1847’s multipart/signed MIME type there is no reliable way to restrict access to facilities setup with faxmail.

BUGS

Only the last instance of a header is kept and written to the output. This means, for example, that only the last of many ’’Received’’ lines will be included in the formatted output.

FILES

~/.hylarc per-user configuration file

/usr/share/fonts/type1/gsfontsfor font metrics
/var/spool/hylafax/tmp/faxmailXXXXXXtemporary files

SEE ALSO

hylafax-client(1), textfmt(1), sendfax(1)