FAXMAIL(1)
NAME
faxmail - HylaFAX mail-to-fax gateway application
SYNOPSIS
faxmail [ options ] [ destination [ from ] ]
DESCRIPTION
faxmail takes an electronic mail message on standard input
and converts it to POSTSCRIPT in a form that is suitable
for transmission as a facsimile. The converted document
is either written to the standard output or, if direct
delivery is enabled, it is submitted directly to a HylaFAX
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 elec-
tronic mail; e.g.
sam: "|/usr/local/bin/faxmail -d 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.
If faxmail is invoked without enabling direct delivery
then it just formats the mail message on the standard
input and writes the result to the standard output. To
enable direct delivery the -d option must be specified on
the command line; see below for more information.
FORMATTING
faxmail formats a mail message according to the following
rules: First it parses the envelope information interpret-
ing any meta-header information (see below) that is pre-
sent. 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 (CIME) 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 resul-
tant POSTSCRIPT or, optionally, how to deliver the result-
ing 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 rudimen-
tary work to:
+o strip out unprintable content such as audio, video, or
binary data,
+o decode encoded parts,
+o insert ``digest dividers'' between multipart/digest
subparts,
+o format message/rfc822 parts as described above for the
top-level envelope, and
+o optionally convert graphical parts (e.g. images) for
display.
MIME processing is fairly simple and (currently) somewhat
constrained. faxmail has builtin support for the follow-
ing MIME parts: text/plain, multipart/mixed, multi-
part/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 ``CIME converters'' directory hierarchy. External
scripts may override builtin processing or supplement 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 result is appended to the output
PostScript document. Otherwise if the part has builtin
support then it is processed directly. Any part that does
not have external or builtin support is discarded and
replaced by a message that indicates the part was removed.
This discarded message can be suppressed with the MarkDis-
carded configuration parameter (also settable with an X-
FAX-MarkDiscarded line in the envelope).
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; multi-
part/digest are burst and an optional ``digest divider''
marking may be inserted before each subpart; mes-
sage/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 pro-
logue section of the generated PostScript document to per-
mit 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.
In general it is recommended that senders either permit
faxmail to format message contents or completely bypass
the formatting facilities and submit data that is to be
processed by sendfax. Trying to combine the two facili-
ties by, for example, combining PostScript with text that
is to be formatted is unlikely to work well because fax-
mail does not track the amount of space on the page that a
non-text MIME part uses.
DIRECT DELIVERY
When faxmail is invoked with the -d option it delivers the
formatted document directly to a HylaFAX server for trans-
mission as facsimile. Command line arguments may be sup-
plied to specify the delivery destination and sender iden-
tity; typically from information extracted by the mail
transport facility. A command line destination is speci-
fied 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 fax-
mail will extract it from the ``From'' line in the enve-
lope. faxmail will not submit a message for delivery if
either the dialstring or sender identity is missing or
null.
When direct delivery is enabled X-FAX- header lines may be
included in the mail message envelope to control the sub-
mission 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 mes-
sage envelope.
OPTIONS
-1 Set text in one column (default).
-2 Set text two columns.
-b font Make font, a POSTSCRIPT font name, the ``bold
font'' used to set header lines. The default
bold font is Helvetica-Bold.
-c Clip long text lines instead of wrapping them at
page margins.
-d Enable direct delivery of facsimile; the format-
ted document will be submitted directly to a
HylaFAX server for transmission as facsimile.
This option is similar to piping the output of
faxmail to the input of sendfax(8C) except when
direct delivery is enabled faxmail interprets
``x-fax-'' header lines in the envelope of the
mail message to look for control information to
use in delivering the facsimile and, by default,
no automatic cover page generation is done.
-f font Make font, a POSTSCRIPT font name, the text font
used to set the body of mail messages. The
default text font is Courier.
-H height Use height as the height, in inches, of the out-
put page. The default page height is taken from
the default page size.
-i font Make font, a POSTSCRIPT font name, the ``italic
font'' used to set header lines. The default
italic font is Helvetica-Oblique.
-Ml=#,r=#,t=#,b=#
Set the page margins; the default margins are:
left and right .25 inch, top .35 inch, bottom
.25 inch.
-n Suppress auto cover page generation when doing
direct delivery.
-p size Set all text using size for the font point size.
-r Set pages rotated by 90 degrees (in ``Landscape
mode'').
-R Set pages unrotated (in ``Portrait mode'').
-s size Set the page size to use. Cover pages are nor-
mally generated using a system-default page size
(usually letter-size pages, 8.5" by 11", for
sites in North America). Alternate page sizes
are specified symbolically using either the name
or abbreviation of an entry in the pagesizes(5F)
database; e.g. a3 (ISO A3), a4 (ISO A4), a5
(ISO A5), a6 (ISO A6), b4 (ISO B4), na-let
(North American Letter), us-leg (American
Legal), us-led (American Ledger), us-exe (Ameri-
can Executive), jp-let (Japanese Letter), and
jp-leg (Japanese Legal). Comparisons are case-
insensitive and any match of a substring of the
full page-size name is sufficient; e.g.
``legal'' would match ``American Legal''.
-u user Set the user name to use when logging in to do
direct delivery. By default the user is speci-
fied by the MailUser configuration parameter
(see below). If a null user name is specified,
then the facsimile will be submitted using the
identity of the user that invoked faxmail.
-v Enable tracing of envelope, MIME, and job sub-
mission processing. Diagnostic information is
written to the standard error (envelope and MIME
processing) and standard output (job submis-
sion).
-W width Use width as the width, in inches, of the output
page. The default page width is taken from the
default page size.
CONFIGURATION PARAMETERS
faxmail reads configuration information from the files
/usr/local/lib/fax/hyla.conf, and ~/.hylarc; in that
order. Configuration files follow the conventions
described in hylafax(1). The following configuration
parameters are recognized:
Tag Type Default Description
AutoCoverPage boolean Yes automatically generate cover page
BoldFont string Helvetica-Bold font for setting header tags
Columns integer 1 number of columns in formatted output
DigestDivider string - multipart/digest divider POSTSCRIPT command
FontDir string see below directory for font metric files
GaudyHeaders boolean No enable/disable gaudy page headers
Headers string see below headers to retain in envelope
ISO8859 boolean Yes use ISO 8859-1 character encoding
ItalicFont string Helvetica-Oblique font for setting header values
LineWrap boolean Yes wrap/truncate text lines
MailUser string - user identity for doing direct delivery
MarkDiscarded boolean Yes mark discarded CIME body parts
MapHeader string - define header mapping
MIMEConverters string see below pathname of CIME converter scripts
Orientation string portrait orientation of text on page
OutlineMargin inches 0 width of outline line
PageCollation string forward collate pages in forward or reverse direction
PageHeaders boolean Yes enable/disable page headers
PageHeight float - output page height
PageMargins string see below margins for formatted page
PageSize string default output page size from database
PageWidth float - output page width
Prologfile string see below pathname of POSTSCRIPT prologue file
TabStop integer 8 inter-stop setting in characters
TextFont string Courier name of font for setting text
TextLineHeight inches - text formatting line height control
TextPointSize inches see below size to use in setting text
Verbose boolean No trace envelope and CIME processing
Values marked as inches are specified using a syntax that
identifies one of several possible units:
#.##bp big point (1in = 72bp)
#.##cc cicero (1cc = 12dd)
#.##cm centimeter
#.##dd didot point (1157dd = 1238pt)
#.##in inch
#.##mm millimeter (10mm = 1cm)
#.##pc pica (1pc = 12pt)
#.##pt point (72.27pt = 1in)
#.##sp scaled point (65536sp = 1pt)
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.
AutoCoverPage Control whether or not a cover page is
automatically generated for each job.
BoldFont The name of the font to use to set header
tags (i.e. the string to the left of the
``:'').
Columns The number of columns to set text in.
(Equivalent to the -m option.)
DigestDivider The string to emit in the output before
each subpart of a multipart/digest mail
message. This string is typically a
POSTSCRIPT procedure that draws a mark of
some sort. Dividers are expected to use no
more vertical space on the output page than
a line of text.
FontDir The directory where Adobe Font Metric (AFM)
files are located; by default
/usr/share/ghostscript/fonts.
GaudyHeaders Control whether or not to use a gaudy-style
page header. Enabling gaudy headers
implicitly enables page headers.
Headers Define the headers retained from the enve-
lope and specify the order that they should
be emitted in the formatted output. The
set of headers is initialized to ``To From
Subject Cc Date''. Headers specified are
appended to this list except for a
``clear'' header that causes the current
set of headers to be discarded.
ISO8859 Control the use of ISO 8859-1 encoding in
the generated POSTSCRIPT
ItalicFont The name of the font to use to set header
values (i.e. the string to the right of the
``:'').
LineWrap Control whether long text lines are wrapper
or truncated at the right hand margin.
(Equivalent to the -c option.)
MailUser The account name to use to login to a fax
server when doing direct delivery. Note
that this account name is not used for the
identity of the sender; this comes from the
command line or the ``From'' line in the
mail message. If a null account name is
specified, then the facsimile will be sub-
mitted using the identity of the user that
invoked faxmail.
MapHeader Define a substitution for the specified
header that should be done each time the
header is emitted in the formatted enve-
lope. Header tags are matched in a case-
insensitive manner.
MarkDiscarded Control whether discarded MIME parts are
replaced by a text message indicating the
original content was removed.
MIMEConverters The pathname of a directory hierarchy that
has scripts for external processing of MIME
body parts. The default pathname is
/usr/local/sbin/faxmail.
Orientation Control whether pages are oriented horizon-
tally (``landscape'') or vertically (``por-
trait''). (Equivalent to the -r and -R
options.)
OutlineMargin Control whether columns of text have a line
drawn around them and the width of the
line. Setting this parameter to 0 disables
outlines.
PageCollation Control whether the output file has pages
collated in the same order as the input
file (``forward'') or in reverse order
(``reverse).
PageHeaders Control whether page headers are generated.
PageHeight Set the output page height (in inches).
PageMargins Set the output page margins. Margins are
specified as string of the form:
``l=#,r=#,t=#,b=#'' where l indicates the
left margin, r indicates the right margin,
t indicates the top margin, b indicates the
bottom margin, and numbers are interpreted
as inches. (Equvalent to the -M option.)
PageSize Set the output page dimensions by name.
(Equivalent to the -s option.)
PageWidth Set the output page width (in inches).
PrologFile The pathname of a file containing
POSTSCRIPT that should be included in the
prologue section of the generated
POSTSCRIPT. The default prologue file is
/usr/local/lib/fax/faxmail.ps.
TabStop Set the tab stop distance (in characters).
TextFont Set the name of font to use for setting
text. (Equivalent to the -f option.)
TextLineHeight Set the vertical text line height and spac-
ing.
TextPointSize Set the point size to use in setting plain
text. (Equvalent to the -p option.)
Verbose Control tracing envelope and MIME process-
ing.
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 facil-
ities 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 format-
ted output.
FILES
~/.hylarc per-user configuration file
/usr/local/lib/fax/pagesizes page size database
/usr/local/lib/fax/faxmail.ps POSTSCRIPT prologue
/usr/local/lib/fax/hyla.conf system-wide configuration file
/usr/local/lib/fax/faxmail.conf system-wide configuration file
/usr/local/lib/fax/sendfax.conf system-wide configuration file for direct delivery
/usr/local/sbin/faxmail hierarchy for external CIME converters
/usr/share/ghostscript/fonts for font metrics
/usr/tmp/faxmailXXXXXX temporary files
SEE ALSO
hylafax(1) textfmt(1) sendfax(1)