'\" t
.\"<!-- Copyright 2002-2007 Double Precision, Inc.  See COPYING for -->
.\"<!-- distribution information. -->
.\"     Title: courierfax
.\"    Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 10/28/2020
.\"    Manual: Double Precision, Inc.
.\"    Source: Courier Mail Server
.\"  Language: English
.\"
.TH "COURIERFAX" "8" "10/28/2020" "Courier Mail Server" "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
courierfax \- Send faxes via E\-mail
.SH "SYNOPSIS"
.HP \w'\fBsendmail\fR\ 'u
\fBsendmail\fR [\fI5558888\fR@fax]
.HP \w'\fBsendmail\fR\ 'u
\fBsendmail\fR [\fI5558888\fR@fax\-lowres]
.HP \w'\fBsendmail\fR\ 'u
\fBsendmail\fR [\fI5558888\fR@fax\-ignore]
.HP \w'\fBsendmail\fR\ 'u
\fBsendmail\fR [\fI5558888\fR@fax\-cover]
.SH "DESCRIPTION"
.PP
The
courierfax
module (if enabled by the system administrator) sends E\-mail messages by fax\&. Addressing an E\-mail message to the address
5558888@fax
faxes a printed copy of the message to the specified phone number\&.
.PP
The ability to send faxes may be restricted, or not available\&. The E\-mail message may be a MIME\-formatted message\&. All attachments are concatenated and sent together in a single fax transmission\&.
courierfax
only knows how to handle certain kinds of attached\&. Obviously, trying to fax a voice
\&.mp3
attaching is not going to work\&.
courierfax
knows how to handle plain text, Postscript, and PDF MIME attachments\&.
courierfax
might also know what to do with other kinds of attachment, depending on some optional software installed by the system administrator\&.
courierfax
may also be able to read
GIF,
PNG, and
JPEG
images\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Color images are converted to black\-and\-white\&.
.sp .5v
.RE
.PP
Images are faxed with one image per fax page (limiting image sizes to about 1600x2200)\&.
.PP
The message will be returned as undeliverable if
courierfax
doesn\*(Aqt know how to handle a MIME attachment\&. If the first MIME section in the E\-mail message is plain text, the text appears on the fax cover page\&. The sender/recipient information for the cover page is taken from the message\*(Aqs headers\&.
.PP
The default
courierfax
configuration tries to resend the fax for up to eight hours, after which the message is returned as undeliverable\&. The message will also be returned as undeliverable if the fax transmission is interrupted\&. The return bounce will state how many pages were successfully transmitted\&.
.PP
"@fax" may also be followed by additional keywords that specify extra options:
.PP
\-lowres
.RS 4
Send a low\-resolution fax\&.
.RE
.PP
\-ignore
.RS 4
Ignore any attachment types that
courierfax
doesn\*(Aqt understand\&.
.RE
.PP
\-cover
.RS 4
Send a cover page only\&. This is useful in limited situations, with something like this in a
\m[blue]\fB\fBdot-courier\fR(5)\fR\m[]\&\s-2\u[1]\d\s+2
file:
.sp
.if n \{\
.RS 4
.\}
.nf
 \&./Maildir
 ! 5552222@fax\-cover
.fi
.if n \{\
.RE
.\}
This
\&.courier
file faxes the contents of a message, sans any attachments, immediately upon receipt in addition to saving the message in the mailbox\&.
.RE
.SH "FAX TRANSMISSION RECEIPT"
.PP
The sender will receive a fax transmission receipt if the sender requests an ESMTP delivery status notification\&. This is the
\fB\-N\fR
option to
\m[blue]\fB\fBsendmail\fR(8)\fR\m[]\&\s-2\u[2]\d\s+2:
.sp
.if n \{\
.RS 4
.\}
.nf
sendmail \-Nsuccess 5556666@fax <messagefile
.fi
.if n \{\
.RE
.\}
.PP
When using other mail software, consult the mail software\*(Aqs documentation for instructions on requesting ESMTP delivery status notifications\&.
.SH "ADDITIONAL DIALING OPTIONS"
.PP
courierfax
configurations that are generated by the
\fBwebadmin\fR
tool for North American environments usually restrict phone numbers to a standardized ten\-digit telephone number, so that the fax address is always <\fIaaabbbcccc\fR@fax>, and
courierfax
silently performs any needed conversion to dial the number (such as adding
\(lq1\(rq
or dropping the local areacode)\&.
.PP
It is also possible to reconfigure
courierfax
so that it accepts any telephone string and dials it without any preprocessing\&. If so, the address may contain any combination of digits, letters
\(lqA\(rq,
\(lqB\(rq,
\(lqC\(rq, and
\(lqD\(rq, representing the four extra dialing tones not normally accessible from most telephone keypads, the symbols
\(lq*\(rq
and
\(lq#\(rq, or the following characters:
.PP
W
.RS 4
Most faxmodems pause and wait for a secondary dialtone, before dialing the rest of the number\&.
.RE
.PP
\-
.RS 4
The dash is replaced by a comma in the dialing string\&. A comma results in most faxmodems pausing for two or three seconds before dialing the rest of the number\&. It is not possible to enter a comma directly, because commas are used to separate multiple E\-mail addresses\&. Use dashes instead of commas in the dialing string\&.
courierfax
replaces all dashes with commas before dialing the faxmodem\&.
.RE
.PP
+
.RS 4
Similarly,
courierfax
replaces all pluses with
\(lq@\(rq
characters before dialing\&. An
\(lq@\(rq
characters results in most faxmodems waiting for the line to be silent for five seconds before dialing the rest of the number\&. It is not possible to enter a
\(lq@\(rq
directly as part of the telephone number itself, for the obvious reasons\&. Use pluses instead of
\(lq@\(rqs in the dialing string\&.
courierfax
replaces all pluses with
\(lq@\(rq
before dialing the faxmodem\&.
.RE
.SH "CONFIGURATION"
.PP
The slightly arcane configuration file,
/etc/courier/faxrc, sets up which dialing strings are valid\&. The default configuration file contains judicious comments that explain all the parameters, and what they do\&. The default configuration file disables
courierfax
by rejecting all telephone numbers\&. The file must be edited in accordance with the embedded instructions, in order to enable faxing\&.
.PP
Using
\fBwebadmin\fR
is highly recommended\&. Upon demand,
\fBwebadmin\fR
will install a suitable configuration file for the North American numbering plan, that receives all telephone numbers as ten\-digit numbers, and adds any required long distance prefix, or removes the local area code, as appropriate\&. Or,
\fBwebadmin\fR
will install a bare\-bones configuration file that dials any requested phone number, without any editing or transformation\&.
.SH "BUGS"
.PP
There is no good way to sleep until a modem lock is released, so we poll every minute\&.
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBcourier\fR(8)\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
\fBdot-courier\fR(5)
.RS 4
\%http://www.courier-mta.org/dot-courier.html
.RE
.IP " 2." 4
\fBsendmail\fR(8)
.RS 4
\%http://www.courier-mta.org/sendmail.html
.RE
.IP " 3." 4
\fBcourier\fR(8)
.RS 4
\%http://www.courier-mta.org/courier.html
.RE