537 lines
14 KiB
HTML
537 lines
14 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>GT::Mail::BulkMail - A simplified interface to sending bulk emails</title>
|
|
<link rev="made" href="mailto:root@penguin.office.gossamer-threads.com" />
|
|
|
|
<style type="text/css">
|
|
/* $MVD$:fontset("Untitled Font Set 1","ARIEL","HELVETICA","HELV","SANSERIF") */
|
|
/* $MVD$:fontset("Arial","Arial") */
|
|
/* $MVD$:fontset("Arial Black","Arial Black") */
|
|
/* $MVD$:fontset("Algerian","Algerian") */
|
|
|
|
|
|
body {
|
|
background-color: white;
|
|
font-family: Verdana, Arial, sans-serif;
|
|
font-size: small;
|
|
color: black;
|
|
}
|
|
|
|
|
|
p {
|
|
background-color : white;
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
h1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
background-color : white;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
h2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : medium;
|
|
font-weight : bold;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h3 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : medium;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : maroon;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h5 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : blue;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
h6 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : small;
|
|
color : black;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
ul {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
ol {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
li {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
th {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
td {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dl {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dd {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
dt {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
code {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
|
|
pre {
|
|
font-family : Courier;
|
|
font-size : small;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-H1 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : bold;
|
|
font-size : 14.0pt;
|
|
background-color : transparent;
|
|
background-image : none;
|
|
color : maroon;
|
|
}
|
|
|
|
|
|
.mvd-H2 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 12.0pt;
|
|
color : blue;
|
|
}
|
|
|
|
|
|
p.indent {
|
|
font-family : "Verdana, Arial, sans-serif";
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-indent {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : circle;
|
|
list-style-position : inside;
|
|
color : black;
|
|
margin-left : 16.0pt;
|
|
}
|
|
|
|
|
|
pre.programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE-programlisting {
|
|
font-size : 9.0pt;
|
|
list-style-type : disc;
|
|
margin-left : 16.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-PRE {
|
|
font-size : 9.0pt;
|
|
}
|
|
|
|
|
|
p.note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P-note {
|
|
margin-left : 28.0pt;
|
|
}
|
|
|
|
|
|
.mvd-H4 {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-weight : normal;
|
|
font-size : 9.0pt;
|
|
color : black;
|
|
margin-left : 6.0pt;
|
|
margin-top : -14.0pt;
|
|
}
|
|
|
|
|
|
.mvd-P {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
font-size : 10.0pt;
|
|
color : black;
|
|
}
|
|
|
|
.mvd-BODY {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
background-color : white;
|
|
}
|
|
|
|
|
|
p.indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
|
|
|
|
.mvd-P-indentnobullet {
|
|
font-family : Verdana, Arial, sans-serif;
|
|
list-style-type : none;
|
|
}
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body style="background-color: white">
|
|
|
|
<p><a name="__index__"></a></p>
|
|
<!-- INDEX BEGIN -->
|
|
|
|
<ul>
|
|
|
|
<li><a href="#name">NAME</a></li>
|
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
|
<li><a href="#description">DESCRIPTION</a></li>
|
|
<li><a href="#requirements">REQUIREMENTS</a></li>
|
|
<ul>
|
|
|
|
<li><a href="#methods">METHODS</a></li>
|
|
</ul>
|
|
|
|
</ul>
|
|
<!-- INDEX END -->
|
|
|
|
<hr />
|
|
<p>
|
|
</p>
|
|
<h1><a name="name">NAME</a></h1>
|
|
<p>GT::Mail::BulkMail - A (perhaps overly) simplified interface to sending bulk emails</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
|
<pre>
|
|
$mailer = new GT::Mail::BulkMail;
|
|
$mailer->option("setting");
|
|
$mailer->otheroption("othersetting");
|
|
...
|
|
|
|
-- or --</pre>
|
|
<pre>
|
|
$mailer = new GT::Mail::BulkMail(
|
|
-option => "setting",
|
|
-otheroption => "othersetting",
|
|
...
|
|
);</pre>
|
|
<pre>
|
|
-- then --</pre>
|
|
<pre>
|
|
sub subroutine {
|
|
# Code to generate the next e-mail address
|
|
}
|
|
open FILE, "email_list.txt";
|
|
%hash = ( 1 => 'some@fictional.address',
|
|
2 => 'who@knows.where'
|
|
);
|
|
@array = ('yet@another.fictional.address','and@one.more');
|
|
$mailer->send(\&subroutine,\*FILE,\%hash,\@array);
|
|
close FILE;</pre>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="description">DESCRIPTION</a></h1>
|
|
<p>GT::Mail::BulkMail is a module to handle mass mailings. It is capable of
|
|
using either sendmail, or an SMTP server. It has the advantage of
|
|
not requiring multiple connections to the SMTP server.</p>
|
|
<p>
|
|
</p>
|
|
<hr />
|
|
<h1><a name="requirements">REQUIREMENTS</a></h1>
|
|
<p>Perl 5.004</p>
|
|
<p>
|
|
</p>
|
|
<h2><a name="methods">METHODS</a></h2>
|
|
<p>All methods can be specified at object creation time as an option with the:
|
|
-option => value syntax. For example, <code>$mailer = new GT::Mail::BulkMail(-from => "foo@bar.com")</code>
|
|
would have the same effect as: <code>$mailer = new GT::Mail::BulkMail(); $mailer->from("foo@bar.com")</code></p>
|
|
<dl>
|
|
<dt><strong><a name="item_smtp">smtp</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the SMTP server to use, and sets the object mail sending method to use SMTP. Takes
|
|
SMTP server as argument.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_sendmail">sendmail</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the sendmail executable to use. Takes the path to sendmail as the argument.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_text">text</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Specifies that the mail format is text. This translates into Content-type: text/plain.
|
|
This is the default format.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_html">html</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Specifies that the mail format is HTML. (Content-type: text/html)
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_headers">headers</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Returns any custom headers set as a hash reference in scalar context, or a hash in list context.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_add_header">add_header</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Adds a single header. This can be any header starting with ``X-'' (Note that X-Mailer headers
|
|
will be prepended with the GT::Mail::BulkMail X-Mailer header (which includes the perl version,
|
|
OS name, GT::Mail::BulkMail module and CVS versions, and the Gossamer Threads homepage)). Pass
|
|
two arguments: A key (header name) and a value (header value). For example, for
|
|
<code>X-Foo: blah blah blah</code> you would use: $mailer->add_header(``X-Foo'' => ``blah blah blah'')
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_add_headers">add_headers</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Same as above, except it adds multiple headers. Has the same argument format. You would use:
|
|
$mailer->add_headers(``X-Foo1'' => ``blah'', ``X-Foo2'' => ``blah blah'');
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_delete_header">delete_header</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Deletes a single header. Pass the name of the header to delete.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_delete_headers">delete_headers</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Delete multiple headers. Pass a list of names of headers to delete.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_from">from</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the ``from'' field of the e-mail. Must be set before $mailer-><a href="#item_send"><code>send()</code></a> can be called.
|
|
Must be set to an e-mail address. If this e-mail address is rejected by the SMTP server,
|
|
no e-mails will be sent.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_name">name</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the ``name'' field of the e-mail. This affects what is displayed in the ``From'' field.
|
|
When sending the email, the actual field will be set to: <code>"This name" <some@name.net></code>.
|
|
Optional.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_subject">subject</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Sets the subject of the message. If not specified, it will default to ``(no subject)''
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_message">message</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
The body of the message. Can be left blank, but that seems rather pointless...
|
|
The message will be encoded using the quoted-printable format if it contains characters
|
|
outside the 7-bit range.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_success">success</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
A code reference to be run for each and every successful e-mail sending.
|
|
Each call to this code reference will be given the e-mail address as the only argument
|
|
(unless using a message ID, which is discussed below). Optional.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_failure">failure</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
A code reference that will be run for any email addresses that cannot be sent. Each
|
|
call to this code reference will be given the ID or e-mail address as the argument
|
|
(message IDs are discussed below). Optional.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_frompresend">frompresend</a></strong><br />
|
|
</dt>
|
|
<dt><strong><a name="item_namepresend">namepresend</a></strong><br />
|
|
</dt>
|
|
<dt><strong><a name="item_subjectpresend">subjectpresend</a></strong><br />
|
|
</dt>
|
|
<dt><strong><a name="item_messagepresend">messagepresend</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
A code reference that will be run before sending an e-mail. The 'from', 'name', 'subject',
|
|
or 'message' field will be sent to the code references (depending on which method called)
|
|
and whatever is returned will be used as the actual field for the email sent. This can be
|
|
used to parse fields to customize them for each recipient. The subroutine is called with
|
|
two arguments: (ID_OR_EMAIL, FIELD). If an ID is provided, it will be passed as the
|
|
first argument, otherwise the email address will be passed. The second argument is the
|
|
field itself. The field used in the actual email to the user will be the value returned by
|
|
the subroutine.
|
|
</dd>
|
|
<dd>
|
|
<p>The default field (for the rest of the mailing) can be changed by directly modifying $_[1]
|
|
itself.</p>
|
|
</dd>
|
|
<dd>
|
|
<p>If the subroutine reference returns an undefined value, the mailer will use the actual field
|
|
instead. You can use this technique to only modify some messages, but not others.</p>
|
|
</dd>
|
|
<dd>
|
|
<p>Optional.</p>
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_show_errors">show_errors</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
If set to something true it will <code>warn()</code> on all errors. Optional. The default is turned on,
|
|
but can easily be changed by modifying the line '
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_error_code">error_code</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Takes a code reference - the code reference will be called with the error as the argument
|
|
when an error occurs. Optional.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_send">send</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
Takes any number of the following arguments:
|
|
</dd>
|
|
<dl>
|
|
<dt><strong><a name="item_array_reference">array reference</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
An array reference of a list of e-mail addresses to send to. After each message, either the
|
|
success or failure callback will be called with the e-mail address as the argument, and
|
|
possibly a message as the second argument.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_hash_reference">hash reference</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
A hash reference of ID => email pairs. For example,
|
|
123 => <a href="mailto:'someone@whoknows.com'.">'someone@whoknows.com'.</a> The value will be used as the e-mail address to send
|
|
to, and the key will be an identifier to pass into the success or failure callbacks.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_glob_reference">glob reference</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
A glob reference to an open file. Make sure the file is opened before passing this!
|
|
The file should contain one e-mail address per line.
|
|
</dd>
|
|
<p></p>
|
|
<dt><strong><a name="item_subroutine_or_code_reference">subroutine or code reference</a></strong><br />
|
|
</dt>
|
|
<dd>
|
|
You may pass a code reference, and it will be called for each e-mail address. It is
|
|
assumed that the subroutine will return one e-mail address each time called, and
|
|
that a return value of ``undef'' indicates that there are no more e-mail addresses.
|
|
The code reference could alternatively return two items - if it does, it is assumed that
|
|
the first is an ID code, and that the second is the email address. When a call to either
|
|
or the success or failure callbacks, the ID will be provided as the first argument
|
|
instead of the e-mail address itself.
|
|
</dd>
|
|
<dd>
|
|
<p>One cool feature to note about using code refs is that you can call <code>next()</code> from within
|
|
the code reference and it will then recall the code reference for the next value.</p>
|
|
</dd>
|
|
</dl>
|
|
</dl>
|
|
|
|
</body>
|
|
|
|
</html>
|