FAXMAIL(1)FAXMAIL(1)NAMEfaxmail - HylaFAX mail-to-fax gateway application
SYNOPSISfaxmail [ options ] [ destination [ from ] ]
DESCRIPTIONfaxmail takes an electronic mail message on standard input and converts
it to POSTSCRIPT® in a form that is suitable for transmission as a fac‐
simile. The converted document is either written to the standard out‐
put 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 facsim‐
ile gateway services. For example, mail aliases may be created to
automatically transmit electronic mail; e.g.
sam: "|/usr/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.
FORMATTINGfaxmail formats a mail message according to the following rules: First
it parses the envelope information interpreting any meta-header infor‐
mation (see below) that is present. Once the entire envelope has been
collected it emits a formatted set of header lines if the -N option has
not been used. 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 PROCESSINGfaxmail 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 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 Sub‐
ject From Cc'' (depending on what headers are present). Note in par‐
ticular 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 PROCESSINGfaxmail parses MIME mail messages and does some rudimentary work to:
· strip out unprintable content such as audio, video, or binary data,
· decode encoded parts,
· insert ``digest dividers'' between multipart/digest subparts,
· format message/rfc822 parts as described above for the top-level
envelope, and
· optionally convert graphical parts (e.g. images) for display.
MIME processing is fairly simple and (currently) somewhat constrained.
faxmail has built-in support for the following MIME parts: text/plain,
multipart/mixed, multipart/digest, message/rfc822, application/post‐
script, 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 supplement the builtin support. For each MIME
body part with type T and subtype S faxmail checks first for an exe‐
cutable script named T/S in the converter hierarchy. If a script
exists then it is run and the result is appended as a new page to the
output PostScript document. (The script is expected to produce inde‐
pendently complete pages.) 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 MarkDiscarded configuration parameter (also settable with an X-FAX-
MarkDiscarded line in the envelope).
The built-in handling support is as follows: text/plain parts are for‐
matted 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 insuffi‐
cient 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/col‐
umn); application/postscript are copied through untouched to the out‐
put; 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.
In general it is recommended that senders either permit faxmail to for‐
mat message contents or completely bypass the formatting facilities and
submit data that is to be processed by sendfax. Trying to combine the
two facilities by, for example, combining PostScript with text that is
to be formatted is unlikely to work well because faxmail 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 transmission as facsimile.
Command line arguments may be supplied to specify the delivery destina‐
tion 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 dial‐
string to use in delivery can also be specified with an X-FAX-Dial‐
string 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.
When direct delivery is enabled 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 send‐
fax 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-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 mar‐
gins.
-C cover Use the cover page template file specified by cover.
-d Enable direct delivery of facsimile; the formatted document
will be submitted directly to a HylaFAX server for transmis‐
sion as facsimile. This option is similar to piping the out‐
put 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 output 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 deliv‐
ery.
-N Suppress the formatting of envelope headers.
-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 normally 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 (American 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''.
-S tsi Pass tsi to the server as the suggested sender identification
to be used, for example, in tagline imaging and fax protocol.
-t when Notify the sender of job status according to when.
-T Trim leading blank lines on text parts.
-u user Set the user name to use when logging in to do direct deliv‐
ery. By default the user is specified by the MailUser con‐
figuration 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. On the command-
line, the login password may also be provided by separating
it from the owner login name with a colon, like
``owner:pass''.
-v Enable tracing of envelope, MIME, and job submission process‐
ing. Diagnostic information is written to the standard error
(envelope and MIME processing) and standard output (job sub‐
mission).
-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 PARAMETERSfaxmail reads configuration information from the files
/usr/share/fax/hyla.conf, /usr/share/fax/faxmail.conf, and ~/.hylarc;
in that order. Configuration files follow the conventions described in
hylafax-client(1). The following configuration parameters are recog‐
nized:
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
FontPath 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 MIME body parts
MapHeader string - define header mapping
MIMEConverters string see below pathname of MIME 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 MIME 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 cor‐
respond 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 typi‐
cally 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.
FontPath The path where Adobe Font Metric (AFM) files are
located; by default
%rom%Resource/Init/:%rom%lib/:/usr/share/ghost‐
script/8.64/Resource/Init:/usr/share/ghost‐
script/8.64/lib:/usr/share/ghost‐
script/8.64/Resource/Font:/usr/share/ghost‐
script/fonts:/usr/share/fonts/default/ghost‐
script:/usr/share/fonts/default/type1:/usr/share/ghost‐
script/fonts:/usr/share/ghost‐
script/8.64/Resource:/usr/share/ghost‐
script/Resource:/usr/share/ghostscript/CID‐
Font:/usr/share/fonts/ttf:/usr/share/fonts/type1:/usr/share/fonts/default/Type1.
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 envelope and spec‐
ify the order that they should be emitted in the format‐
ted 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 mes‐
sage. If a null account name is specified, then the
facsimile will be submitted 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 envelope. 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/share/fax/faxmail. HylaFAX comes with
default converter scripts for TIFF and PDF, and they can
be found in that path and used as a reference for con‐
structing other converters. The script is passed the
filename of the body part for conversion as the first
parameters. Subsequent parameters are the MIME Content-
Description, Content-ID, and Content-Disposition infor‐
mation prefixed with ``description:'', ``id:'', and
``disposition:'' respectively.
Orientation Control whether pages are oriented horizontally (``land‐
scape'') or vertically (``portrait''). (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 indi‐
cates the left margin, r indicates the right margin, t
indicates the top margin, b indicates the bottom margin,
and numbers are interpreted as inches. (Equivalent 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/share/fax/faxmail.ps.
TabStop Set the tab stop distance (in characters).
TextFont Set the name of font to use for setting text. (Equiva‐
lent to the -f option.)
TextLineHeight Set the vertical text line height and spacing.
TextPointSize Set the point size to use in setting plain text.
(Equivalent to the -p option.)
Verbose Control tracing envelope and MIME processing.
NOTES
Because a sender's identity in an electronic mail message is inherently
untrustworthy, using faxmail to build a mail to fax gateway is problem‐
atic. Unless mail service is somehow restricted or the sender's iden‐
tity 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/fax/pagesizes page size database
/usr/share/fax/faxmail.ps POSTSCRIPT prologue
/usr/share/fax/hyla.conf system-wide configuration file
/usr/share/fax/faxmail.conf system-wide configuration file
/usr/share/fax/sendfax.conf system-wide configuration file for direct delivery
/usr/share/fax/faxmail hierarchy for external MIME converters
%rom%Resource/Init/:%rom%lib/:/usr/share/ghostscript/8.64/Resource/Init:/usr/share/ghostscript/8.64/lib:/usr/share/ghostscript/8.64/Resource/Font:/usr/share/ghostscript/fonts:/usr/share/fonts/default/ghostscript:/usr/share/fonts/default/type1:/usr/share/ghostscript/fonts:/usr/share/ghostscript/8.64/Resource:/usr/share/ghostscript/Resource:/usr/share/ghostscript/CIDFont:/usr/share/fonts/ttf:/usr/share/fonts/type1:/usr/share/fonts/default/Type1for font metrics
/var/spool/fax/tmp/faxmailXXXXXXtemporary files
SEE ALSOhylafax-client(1), textfmt(1), sendfax(1)
July 22, 1996 FAXMAIL(1)
