FAXMAIL(1)

📦
version 7.0.11 · 7 versions
, in fedora 43, fedora 44

💌 faxmail(1) — the mail-to-fax gateway of your dreams 💌

HylaFAX · General Commands Manual · faxmail(1)

✨ NAME ✨

faxmail — the HylaFAX mail-to-fax gateway application 🫶

🌸 SYNOPSIS 🌸

faxmail [ -O config ] [ options ] [ destination [ from ] ]

💖 DESCRIPTION 💖

okay bestie, listen. faxmail takes an electronic mail message that shows up on standard input and converts it into POSTSCRIPT® in a form that is suitable for transmission as a facsimile. like, actually suitable. and then that converted document is either written to the standard output, or — if direct delivery is enabled — it gets submitted directly to a HylaFAX server for transmission. two paths, one icon 💅

faxmail is designed for use in constructing electronic mail to facsimile gateway services. so, 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. main character energy, honestly 👑

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. no delivery, no drama, just vibes. 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 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 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. so many knobs, we love a customizable queen ✨

🦋 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 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. iykyk 💅

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. lowkey the cleanest move 🙈

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''. glow-up, but for headers 💖

🌈 MIME PROCESSING 🌈

faxmail 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/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 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 as a new page to the output PostScript document. (The script is expected to produce independently 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 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. noted and filed 📝

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 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.

⚠️ bestie, pick a lane on this one. mixing the two is giving chaos, not giving results.

💅 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 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. no dialstring, no sender, no delivery. rules are rules 🚫

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 `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 ✨

okay bestie, here's the whole menu of things you can tell faxmail to do. every flag, every default, no skips 💅

  • -1 — set the text in one column. this is the default, she's the baseline ✨
  • -2 — set the text in two columns. twin vibes.
  • -b font — makes font (a POSTSCRIPT font name) the ``bold font'' used to set header lines. the default bold font is Helvetica-Bold.
  • -c — clip those long text lines instead of wrapping them at word boundaries near the page margins. so if a line is too long, she gets cut off, periodt ✂️
  • -C cover — use the cover page template file specified by cover. custom cover, main character energy 💖
  • -d — enable direct delivery of facsimile. the formatted document gets submitted directly to a HylaFAX server for transmission as facsimile. this is similar to piping the output of faxmail to the input of sendfax(8C) — except that when direct delivery is on, 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 — makes 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 — makes 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. l = left, r = right, t = top, b = bottom, iykyk 🫶
  • -n — suppress auto cover page generation when doing direct delivery. no cover, no problem.
  • -N — suppress the formatting of envelope headers. bye headers 👋
  • -O config — treat config as a configuration parameter specification that gets interpreted after reading the configuration file. like, for example, -O Host:fax.example.com'' would set the `Host` configuration parameter to fax.example.com'', overriding whatever was in the configuration file. override slay 🔥
  • -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''. substring matching? so real 🌸
  • -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. the options are done'', req'' (for re-queued), none''/off'', or ``default''.
  • -T — trim leading blank lines on text parts. clean it up 🧹
  • -u user — set the user name to use when logging in to do direct delivery. by default the user is specified 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. 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 processing. diagnostic information is written to the standard error (envelope and MIME processing) and standard output (job submission). she's telling you EVERYTHING 🔍
  • -W width — use width as the width, in inches, of the output page. the default page width is taken from the default page size.
ngl, that's a lot of knobs. you don't need all of them at once bestie, promise 💜

✨ CONFIGURATION PARAMETERS ✨

okay bestie, faxmail is reading its config tea from three files, and the order is literally this: /etc/hylafax/hyla.conf, then /etc/hylafax/faxmail.conf, then ~/.hylarc. That exact order. These files follow the conventions described in hylafax-client(1). The following configuration parameters are recognized:

  • AutoCoverPage — boolean — default Yes — automatically generate cover page
  • BoldFont — string — default Helvetica-Bold — font for setting header tags
  • Columns — integer — default 1 — number of columns in formatted output
  • DigestDivider — string — default - — multipart/digest divider POSTSCRIPT command
  • FirstAlternativeOnly — boolean — default Yes — only use the first alternative part
  • FontPath — string — default see below — directory for font metric files
  • GaudyHeaders — boolean — default No — enable/disable gaudy page headers
  • Headers — string — default see below — headers to retain in envelope
  • ISO8859 — boolean — default Yes — use ISO 8859-1 character encoding
  • ItalicFont — string — default Helvetica-Oblique — font for setting header values
  • LineWrap — boolean — default Yes — wrap/truncate text lines
  • MailUser — string — default - — user identity for doing direct delivery
  • MarkDiscarded — boolean — default Yes — mark discarded MIME body parts
  • MapHeader — string — default - — define header mapping
  • MIMEConverters — string — default see below — pathname of MIME converter scripts
  • Orientation — string — default portrait — orientation of text on page
  • OutlineMargin — inches — default 0 — width of outline line
  • Overstrike — boolean — default No — overstrike interpretation of lone carriage returns
  • PageCollation — string — default forward — collate pages in forward or reverse direction
  • PageHeaders — boolean — default Yes — enable/disable page headers
  • PageHeight — float — default - — output page height
  • PageMargins — string — default see below — margins for formatted page
  • PageSize — string — default default — output page size from database
  • PageWidth — float — default - — output page width
  • Prologfile — string — default see below — pathname of POSTSCRIPT prologue file
  • TabStop — integer — default 8 — inter-stop setting in characters
  • TextFont — string — default Courier — name of font for setting text
  • TextLineHeight — inches — default - — text formatting line height control
  • TextPointSize — inches — default see below — size to use in setting text
  • TrimText — boolean — default No — trim leading blank lines on text parts
  • UseAlternativePart — integer — default 1 — which part to use in a set of alternatives
  • Verbose — boolean — default 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 correspond to a command line option. Parameter values identified above as inches are converted according to the conventions described above.

AutoCoverPage — do you want a cover page automatically generated for each job? This parameter controls exactly that.

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.

FirstAlternativeOnly, UseAlternativePart — in a multipart/alternative MIME section, whether or not to only format the first part. A multipart/alternative MIME section is typically used to present the mail client with a selection of alternatives which contain the same basic content (such as a text/plain and a text/html part). Thus the mail client has the opportunity to select which part is best-suited for its purpose. Generally the most-portable format (text/plain) is the first alternative. These options allow parts to be stripped when presented in a multipart/alternative section and prevents duplicate parts from being formatted. FirstAlternativeOnly: true is synonymous with UseAlternativePart: 1 while FirstAlternativeOnly: false is synonymous with UseAlternativePart: 0 (which causes all alternatives to be formatted). In order to format only the text/html part then UseAlternativePart: 2 should work.

FontPath — the path where Adobe Font Metric (AFM) files are located; by default /usr/share/ghostscript/Resource/Init:/usr/share/ghostscript/lib:/usr/share/ghostscript/Resource/Font:/usr/share/ghostscript/fonts:/usr/share/fonts/urw-base35:/usr/share/fonts/google-droid-sans-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 envelope 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 wrapped 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 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 /etc/hylafax/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 constructing other converters. The script is passed the filename of the body part for conversion as the first argument. Subsequent arguments are the MIME Content-Description, Content-ID, Content-Disposition, Content-Type name, and Content-Disposition filename information which are each preceded by their respective -description, -id, -disposition, -name, or -filename argument.

Orientation — control whether pages are oriented horizontally (landscape) 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 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. (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 /etc/hylafax/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 spacing.

TextPointSize — set the point size to use in setting plain text. (Equivalent to the -p option.)

TrimText — control whether or not leading blank lines will be trimmed from text parts. If the text part is completely empty, it will effectively be skipped. (Equivalent to the -T option.)

Verbose — control tracing envelope and MIME processing.

💀 NOTES 💀

okay bestie, real talk, this part is the tea and it's a lil spicy 🔥 so listen up:

Because a sender's identity in an electronic mail message is inherently untrustworthy (yeah, fr fr, mail headers are basically the group chat screenshot of the internet — anyone can fake them 💀), using faxmail to build a mail to fax gateway is problematic. Not "oops awkward" problematic, like actually-problematic 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.

⚠️ so like, if you're out here building a gateway off faxmail with zero verification, you're basically leaving the door unlocked with a lil sign that says "come on in, send faxes on our dime 🫶". don't do that.

🐛 BUGS 🐛

ngl there's exactly one bug and it's giving "we know, and we're telling you anyway":

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

🙈 so if you were hoping to see the whole lil paper trail of every hop your mail took, bestie… you get one. the final one. that's it. periodt.

🎀 FILES 🎀

here's the whole lineup of files this icon touches, and yes every single one of them matters 👑

  • ~/.hylarc — per-user configuration file 🌸
  • /etc/hylafax/pagesizes — page size database 📄
  • /etc/hylafax/faxmail.ps — POSTSCRIPT prologue ✨
  • /etc/hylafax/hyla.conf — system-wide configuration file
  • /etc/hylafax/faxmail.conf — system-wide configuration file
  • /etc/hylafax/sendfax.conf — system-wide configuration file for direct delivery 📠
  • /etc/hylafax/faxmail — hierarchy for external MIME converters 🧚
  • /usr/share/ghostscript/Resource/Init:/usr/share/ghostscript/lib:/usr/share/ghostscript/Resource/Font:/usr/share/ghostscript/fonts:/usr/share/fonts/urw-base35:/usr/share/fonts/google-droid-sans-fonts — for font metrics 🔤
  • /var/spool/hylafax/tmp/faxmailXXXXXX — temporary files 🗂️

👀 SEE ALSO 👀

go read your sisters, they're all iconic too:

okay that's the whole page, you made it to the end, I'm so proud of you 🥹💖 this little legend is from the HylaFAX client crew and it's dated July 22, 1996 — yeah, a vintage icon, still slaying, still the FAXMAIL(1) main character 👑 periodt, go format some mail bestie 🌈

📦 where this page comes from