.TH BULK_MAILER 8
.UC 4
.SH NAME
bulk_mailer \- assist in delivery of mail to large numbers of recipients
.SH SYNOPSIS
\fBbulk_mailer\fP
[-\fBcomment\fP \fIcomment\fP]
[-\fBdebug\fP]
[-\fBdomain\fP \fIdomainname\fP]
[-\fBlist-archive\fB \fItext\fP]
[-\fBlist-help\fB \fItext\fP]
[-\fBlist-owner\fB \fItext\fP]
[-\fBlist-post\fB \fItext\fP]
[-\fBlist-unsubscribe\fB \fItext\fP]
[-\fBmaxdomains\fP \fImaxdomains\fP]
[-\fBmaxrcpts\fP \fImaxrcpts\fP]
[-\fBmaxsize\fP \fImaxsize\fP]
[-\fBowner\fP \fIlist-owner-address\fP]
[-\fBprecedence\fP \fIprecedence-keyword\fP]
[-\fBprivate\fP]
[-\fBreply-to\fP \fIreply-address\fP]
[+\fBreply-to\fP \fIreply-address\fP]
[-\fBs\fP]
[-\fBsendmail\fP \fIsendmail-flags\fP]
[-\fBv\fP]
\fIenvelope-from\fP
\fIrecipient-list-file\fP
.SH DESCRIPTION
.PP
.I Bulk_mailer
reads the message to be sent (with headers already attached) from stdin,
sets \fIenvelope\fP as the envelope return address for the
mailing list, and delivers it to all recipient addresses
listed one-per-line in \fIrecipient-list-file\fP.
It sorts the recipient list by reversed domain (so similar ones sort together),
splits up the recipients into several groups containing no more than N
domains each, creates an SMTP envelope for each group of recipients,
and feeds that envelope to \*Q/usr/lib/sendmail -bs\*U.
.PP
Splitting the envelopes up allows sendmail to perform delivery in parallel,
so instead of having one large queue entry (for which sendmail might take
awhile to get around to attempting delivery for some recipients), it has
several smaller queue entries.  Depending on your point-of-view, this can
still be considered \*Qcluttering up your mail queue\*U, but it does seem to
deliver messages more quickly to most recipients.
.PP
The core of this program was extracted from a somewhat strange mailing
list manager called na-net; it was designed to efficiently send out
mail to 5000 people at a time.
I have used this program to attempt
delivery of a message to over 12000 recipients around the world,
within a few hours.
I'm currently using bulk_mailer as a back-end for
several mailing lists of modest size.
However, the program is not extensively tested, and may not work well
in all environments.
See \*QBUGS\*U below.
.PP
\fIEnvelope_from\fP is the envelope return address for the mailing list.
This should either be the address of a human list maintainer, or 
the address of a robot that tries to recognize bounced mail messages
and grok it, forwarding anything it doesn't understand to a human.
.PP
\fIRecipient_list_file\fP is a filename of a list of recipients, one
recipient per line.
\fBBulk_mailer's\fP address prefrobnicator tries to
understand several forms of address, e.g.:
.sp
.RS
.nf
Keith Moore <moore@cs.utk.edu>
moore@cs.utk.edu (Keith Moore)
"Keith Moore" <"keith.moore"@cs.utk.edu>  (Moore, Keith)
.fi
.RE
.sp
should all do the right thing.
.SH OPTIONS
.TP
.B \-delete-list-hdrs
Delete any List-* header fields that appear in the input.  This option
is automatically set if any of the -list-* options are set.
.TP
.B \-debug
Don't actually mail the stuff.
instead, spit SMTP to stdout
.TP
.BI \-domain \0domainname
Set the local domain name to \fIdomainname\fP.
If not set, \fBbulk_mailer\fP
will try to figure out the name on its own.
Note: This should be a fully-qualified domain name \-
not just the first component (aka the \*Qhostname\*U).
If the domain name doesn't have a '.' it's rejected.
.TP
.BI \-list\-archive \0text
Add a header of the form 'List-Archive: \fItext\fR'.  This should
contain a URL pointing to a list archive, or a mailto: URL which, if
sent a piece of mail, will return instructions to access the list
archive.  The URL should be surrounded by < and >.  
Read RFC 2369 before setting this option.
.TP
.BI \-list\-help \0text
Add a header of the form 'List-Help: \fItext\fR'.  This should contain
a URL of a help file, or a mailto: URL which, if sent a piece of mail,
will cause the help file to be returned.  The URL should be surrounded
by < and >.
Read RFC 2369 before setting this option.
.TP
.BI \-list\-owner \0text
Add a header of the form 'List-Owner: \fItext\fR'.  This should
contain the mailto: URL of the list owner, surrounded by < and >.
Read RFC 2369 before setting this option.
.TP
.BI \-list\-post \0text
Add a header of the form 'List-Post: \fItext\fR'.  This should contain
either the word "NO", or a URL giving the posting address for the
list.  (Normally this will be a mailto: URL, but it might also be a
web page.)
Read RFC 2369 before setting this option.
.TP
.BI \-list\-subscribe \0text
Add a header of the form 'List-Subscribe: \fItext\fR'.  This should
contain the URL (surrounded by < >) of a web page or mail server that
can be used to subscribe to the list.
Read RFC 2369 before setting this option.
.TP
.BI \-list\-unsubscribe \0text
Add a header of the form 'List-Unsubscribe: \fItext\fR'.  This should
contain the URL (surrounded by < >) of a web page or mail server that
can be used to unsubscribe to the list.
Read RFC 2369 before setting this option.
.TP
.BI \-maxdomains \0maxdomains
Set the maximum number of domains per envelope to \fImaxdomains\fP.
If not explicitly set, 20 is the default.
.TP
.BI \-maxrcpts \0maxrcpts
Set the maximum number of recipients per envelope to \fImaxrcpts\fP.
If not explicitly set, 100 is the default.  This is used to work
around a bug in RFC 821 (and in many MTAs) where a permanent error
code is returned when the number of recipients in an SMTP session
exceeds some pre-set limit.
.TP
.BI \-maxsize \0maxsize
Reject any message larger than \fImaxsize\fP bytes.
.TP
.BI \-owner \0list\-owner\-address
Set the list owner address.  If the message looks like a bounce, or if
it contains [un]subscribe commands and the -s flag is set, the mail
will be forwarded to this address instead of being distributed to the list.
.TP
.BI \-precedence \0precedence\-keyword
Add a \*QPrecedence: \fIprecdence-keyword\fP\*U header.
\fIPrecedence-keyword\fP should be a
keyword recognized by sendmail.
NOT RECOMMENDED.
.sp
WARNING: some mailers will bounce the mail if they
see a Precedence header with a keyword they don't
understand; some list managers will silently drop
the mail if they see a Precedence header with a
keyword they do understand.
There is NO safe value
for the Precedence header that won't cause some 
mailer to mishandle the message.
This option is therefore not recommended.
.TP
.B \-private
If this flag is set, and the address in the From header field does not
match the address of one of the list subscribers (or if there is no
From header field), print an error message to stderr and return a
EX_NOPERM exit code.  If bulk_mailer was called from sendmail, this
exit code will cause a nondelivery report to be returned to the
author.
.TP
.BI \-reply-to  \0reply\-address
Add a \*QReply-to: \fIreply-address\fP\*U header to the resent message
if there wasn't one in the input.  
.sp
Use of the reply-to header by lists is questionable;
see http://www.unicom.com/FAQ/reply-to-evil.html
for some of the reasons why.
.TP
.BI \+reply-to \0reply\-address
Add a \*QReply-to: \fIreply-address\fP\*U header to the resent message,
overriding any reply-to header in the input.
NOT RECOMMENDED.
.sp
If having a list use reply-to is questionable, 
overriding the sender's reply-to header is even worse.
This option should be used only in very unusual cases.
.TP
.B \-s
Check for "unsubscribe" or similar administrative requests in the
Subject header field or the message body.  If found, do not
deliver the message to the list recipients but forward it to 
the list owner.
.TP
.BI \-sendmail \0sendmail\-flags
Add \fIsendmail-flags\fP to the sendmail command-line.
For instance, \*Q-sendmail -Odq\*U would have bulk_mailer
pass the \*Q-Odq\*U flag to sendmail, which tells it:
\*Qjust queue the message, don't attempt to deliver it immediately\*U.
.TP
.B \-v
Be verbose.
.PP
To have bulk_mailer distributed mail to a list, add the following
lines to /etc/aliases:
.sp
.RS
.nf
{FOO}-request: whoever-maintains-foo
owner-{FOO}: whoever-maintains-foo
{FOO}: "|{BULK_MAILER} owner-{FOO}@{YOUR.DOMAIN} {ADDRESS_LIST}"
.fi
.RE
.sp
where {FOO} is the name of the list, {YOUR.DOMAIN} is your
fully-qualified domain, {BULK_MAILER} is a full path name of the
bulk_mailer program, and {ADDRESS_LIST} is a full path name of the
file containing the list of addresses. 
.SH DIAGNOSTICS
.SH SEE ALSO
sendmail(8)
The documentation in /usr/doc/bulkmail
.br
G. Neufeld, J. Baer.  
\fIThe Use of URLs as Meta-Syntax for Core Mail 
List Commands and their Transport through Message Header Fields.\fR
RFC 2369, July 1998.
.SH AUTHOR
Keith Moore, <moore@cs.utk.edu>
.SH BUGS
.PP
If your system has per-user process quotas, or a small number of
process table entries, you will want to modify this program to recover
gracefully when these are exhausted.
.PP
The -private flag currently has a number of shortcomings. It always
bounces the message if the author is not a list subscriber (there's no
provision for a moderator), the error message text is hard-coded into
the program, there's no provision for a separate list of people who
are allowed to post even though they are not list subscribers, and the
address matching algorithm only does exact (case-insensitive) matching
\- it doesn't take sub-addresses, or sub-domains, into account.