452 Productions Internet Group (http://www.452productions.com)
# 452 Multi-MAIL v1.0
# This script is freeware and is realeased under the GPL
# Copyright (C) 2001 452 Productions
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
# Or just download it http://www.fsf.org/
###############################################################################
Welcome to the readme for the 452 Productions Internet Group Multi-MAIL v1.0.
For reasons of convention and sanity, this document is broken up into a few
sections.
1. Intro and required junk
So just what is this thing? 452 Multi-MAIL is a fully featured mailing list
manager. Some of those features include Socket based e-mail connections enable
the script to handle _much_ larger lists than other PHP mailers which use the
mail () function. A MySQL backend keeps the rest of the script clicking along
at high speed. Multiple lists can be created and users who sign up for more
than one list will not receive duplicate mailings. Users can add remove and
change their mailings without your assistance. You can allow other people
access to the mailing list system and specify which lists they are allowed
to send their messages to. You should be impressed. (Well....)
What do you need to make all this amazing magic happen?
A *nix webserver with apache
PHP 3.0.12+
MySQL should work on just about any version
A SMTP server (Mail server)
2. Installation
As you are reading this, we will assume that you figured out to unzip the
package. Good, top marks for ingenuity. You should have found the following:
readme - This very document
mail_admin.php - The admin interface
mail.php - The user interface
front.php - a trimmed down version of mail.php
add_addys.php - a script to help transfer your list
archive.php - The past mailings browser
common.inc.php - Some common functions
mf.inc.php - a blank file
config.inc.php - a blank file
login_failure.txt - a blank file
A dir named f - The SQL table structures and data that goes into the above
mentioned blank files if you choose not to use the install script
install.php - The install script
Upload all the files except readme and the files contained in the ``f`` dir
to your web server. We will be creative and call this server mydomain.com and
be even more creative and assume that you create a directory called ``mail``
into which you place these scripts. Once the files have been uploaded
execute the command ``chmod 666`` (0666 or rw-rw-rw- depending on how you
input that kind of stuff) for mf.inc.php, config.inc.php and
login_failure.txt. All other files should be ``chmod 755``. (0755 or r-x-r-x-r-x)
Next, direct your web browser to the install script,
http://www.mydomain.com/mail/install.php. Enter the appropriate data.
Database name: The name of your database. If you have already created
one for us to use put that name in, otherwise the script will try and
create it, but support for that is sketchy at best, we suggest you
already have one ready, contact your sysadmin for more info.
Database password: The password to access the aforementioned database
Database username: The user name to accompany the aforementioned password
and database.
Database host: Where the aforementioned database is located. localhost
should work for the vast majority of users.
Base url: Your domain, or your username if you have an account on one of
those free servers. This is a (Weak) security feature, the script checks to
see that it is in the referrer before it executes. It is not recommended that
you use the http:// or www. prefixes anywhere, just mydomain.com or
mydomain.com/username.
SMTP Server: A mail server that you are allowed to connect to, most likely
mail.mydomain.com or mail.myhost.com. You can try mail.myisp.com but it will
most likely not work, more on that later.
Admin e-mail: This is the e-mail that will send your messages regardless of
which admin user sent them. This is also where replies to your mailings will go.
At this point, we need to talk about SMTP anti-relay which our good friend
Jarmug was kind enough to educate us on. Spam is a big problem. One thing
spam senders try to do is ``bounce`` there messages off other people``s mail
servers to make it harder to block and trace. In response, many servers now
have anti-relay. What this means is that if you have a website at mydomain.com
and an isp at myisp.com you may not be able to send mail through mail.myisp.com
EVEN IF you currently send mail from your mail program on your computer through
your isp``s mail server. This is because your website is not local. (If your
isp hosts your web site, nevermind) So, if you don``t already know what
mailserver you are allowed to use ask your sysadmin. Another anti-relay
situation is that most SMTP servers will not allow outgoing mail with a
domain (@blah.com) that is not local. So you will probably not be able
to send mail from mail.mydomain.com with an admin e-mail of
me@otherdomain.com. On that same note, some overly retentive SMTP servers
also check to make sure that you are sending the mail from a valid e-mail
address. So random-made-up-alias@mydomain.com might not work. If this is
the case then some aliases may not work. Long story short, we _strongly_
suggest that for your admin e-mail you choose a real, local e-mail address.
Other wise you``ll have to do all sorts of voodoo to get your message to send.
Its SMTP``s fault, not ours.
Mail admin alias: This is the nice pretty name that will appear in inboxes.
It can be whatever you want it to.
Welcome message and Footer: You can edit these at any time from the admin
console.
Mail admin username: What you the admin will log into the system with
Mail admin password: The password that will accompany the aforementioned
username.
Press go.
Did it work?
The most common error at this point is:
Error creating database: Access denied for user: ``username@localhost`` to
database ``mail``
This means that the database did not exist, but that you do not have
permission to create databases. You will need to ask your sysadmin to
create the database, then run the install.
If you get an error about tables already existing you already have a table
named x. You need to drop it.
If you get an error about file identifiers and permissions, make sure that
you chmod``d everything correctly.
The next page tells you of your success or failure in setting up the database
and writing to various files. Technically at this point you are done. However,
we _strongly_ recommend that you hit the ok button on this screen to send a
test message to yourself. This will allow you to see if your socket connection
works and if you are allowed to post to the SMTP server. It is also
recommended that you use add_addys.php to add a least one e-mail address
that is not local (Like you@hotmail/yahoo/excite.com or something) and test
to see if you can send the message to that address. As long as the SMTP
server accepts the socket connection, you will NOT receive ANY error messages.
This does not imply that your message was successfully sent. More on that in a
bit.
Now head on over to mail_admin.php and login with your username and password.
From here, you should first create a list. The name you give this list will
be seen by people when they sign up, so something like ``General``
or ``News`` would be appropriate. This name can``t have any spaces in it.
The first list you create will be your default list. Once you``ve added your
lists you can edit your footer and welcome message, and add some users and
specify which list(s) they may send to. The welcome and footer messages are
not list specific. We hope to add support for spaces in list names and list
specific welcome and footer messages in the nest update.
If you have a previous mailing list that you want to transfer, head on over
to add_addys.php Simply paste your old mailing list into the box and select
which list(s) these people should get. (That is not always an option, if you
only have one list it defaults to that.) Press go and you will be notified
of your success or failure.
If you got enough errors from the install script to sink the titanic, or you
are a real propeller head and want to do a manual install, look in the folder
named ``f``. Here you will find the SQL table structures and the outline of
config.inc.php. Run the SQL docs to MySQL and edit the config file by hand.
We will assume you know what you are doing if you choose this route.
Section 3: Use.
The process goes something like this. A visitor to your site goes to mail.php
(Or uses front.php which can be called with an include(); and will display
a single form field for their address, they will be added to your default
list. The process is the same no matter which script is called.) and enters
their e-mail address, and if applicable, selects which lists to receive.
They press go, their e-mail address is validated, and we check to make sure
they are not already in the database. The user is then directed to their
mailbox where a confirmation message is waiting. This makes sure that only
valid e-mail address get on the list and that no one tampers with a users
subscription. They click on the link in the message and are then added to
the list(s) they requested. At any time they may visit mail.php and change
their mailings or remove themselves form the list.
You (Or one of your sub-admins) then log into the admin interface.
You as the super-admin have complete access. Your sub admins only have
access to lists that you allow them to and can only send mail; they can``t
do any of the other house cleaning maintenance type stuff you are allowed
to. An admin decides to send a message. They click send mail and fill in
the fields and select which list(s) it will be sent to and press send.
The script will report if it was able to make a socket connection. If it
can then it sends the message. If you are not allowed to post (Write) to
the SMTP server you specified, or if you have violated some anti-relay rule
(See in the install procedure near the SMTP description) or if the script dies
from a maximum time out/run time error, some or all of your messages may not be
sent.
The rest of the admin console is pretty harmless. If a user has trouble
deleting themselves you can manually remove them, you can take off anyone
you don``t want on the list, edit access privileges and remove other admins
and delete past mailings. If you delete past mailings, they are only removed
from your database. We can``t go and erase them from other people``s inboxes.
(Not for lack of trying though)
Visitors to your site can then visit archive.php and browse through mailings
by list.
Section 4: FAQ
I don``t get any errors, but my messages are not being sent. Whats wrong?
Your SMTP server has an anti-relay rule activated and you are violating it.
See the note in the install section by the SMTP definition. If you are sure
you followed those guidelines, your SMTP server may be allowing you to connect
but not post. Contact your sysadmin.
I get a maximum time out/execution error. Whats wrong?
The script could not send the message to everyone on your list fast enough
and the server killed it. We want to know about it. How many people did you
have on your list? Send us an e-mail telling us. This is a common problem
with php mailers using the mail() function which is very slow. By using
sockets we have (In theory) speed the operation up enough to allow you to
send hundreds of thousands of emails. It also depends on server settings.
But ever server will eventually kill this script if you have a very large
number of addresses. (We``re talking millions) On average the mail() function
can send about 5,000 emails before it gets killed. This script should be able
to send at least 100,000. But, as we don``t have 100k people on our list,
we don``t actually know and are just guessing. So if you DO get a timeout
error we WANT to know. We``re also working to speed up the list selection
process, which should allow you to send even more messages.
I don``t know what SMTP server to use. Can I just pick a random domain and use
theirs?
Ummm....no. You probably don``t have access. Ask your host which SMTP server
you can use. The vast majority of web hosts allow SMPT access. If not we can
recommend a few good ones that do.
What with your spelling? Haven``t you ever heard of a spell check?
It is a poor mind that can only imagine one way to spell a word.
That should pretty much do ya. If you still have questions, or found a bug,
(And there``s probably a ton of them) or have a suggestion (And there is a
lot of room for improvement) don``t hesitate to contact us. Other than that
enjoy the script, we hope it``s useful to you. (If not tell us how we could
make it useful)
Services Dept.
services@452productions.com
http://www.452productions.com
World Domination on a Global Scale (TM)
