| 1 |
/* $Id: README.txt,v 1.1.8.5 2008/07/26 20:15:17 philipnet Exp $ */
|
| 2 |
|
| 3 |
|
| 4 |
Contents of this File
|
| 5 |
=====================
|
| 6 |
* Introduction
|
| 7 |
* Maintainers
|
| 8 |
* Installation and configuration
|
| 9 |
* Testing and troubleshooting
|
| 10 |
* Extended use
|
| 11 |
|
| 12 |
|
| 13 |
Introduction
|
| 14 |
============
|
| 15 |
|
| 16 |
The Listhandler module allows you to connect mailing lists to forums and vice
|
| 17 |
versa.
|
| 18 |
|
| 19 |
It works in conjunction with the Mailhandler module. Mailhandler receives an
|
| 20 |
email and then asks Listhandler if the received email is part of a list. If
|
| 21 |
the email is from a mailing list associated with a forum on your site then
|
| 22 |
Listhandler adds the received email to the forum.
|
| 23 |
|
| 24 |
Additionally Listhandler will take every post to a forum and, as long as that
|
| 25 |
forum is associated with a mailing list, post the message to it. Checks are
|
| 26 |
made to ensure that a continuous cycle of emails and posts aren't generated.
|
| 27 |
|
| 28 |
Mailhandler and Listhandler can deal with attachments in emails and in forum
|
| 29 |
posts. See below for configuration details.
|
| 30 |
|
| 31 |
The Listhandler administration page allows you to set an 'anonymous user'
|
| 32 |
email address and configure the mailing list attributes.
|
| 33 |
|
| 34 |
|
| 35 |
|
| 36 |
Maintainers
|
| 37 |
===========
|
| 38 |
Current Maintainer:
|
| 39 |
Philip Ludlam - Drupal 5 and 6 - (http://www.philipnet.com/about)
|
| 40 |
|
| 41 |
Previous maintainer:
|
| 42 |
Gerhard Killesreiter - Drupal 4.6 and 4.7 - (http://drupal.org/services#gerhard)
|
| 43 |
|
| 44 |
|
| 45 |
|
| 46 |
Installation and configuration
|
| 47 |
==============================
|
| 48 |
|
| 49 |
1) Listhandler works best with an already working mailing list. Please set one
|
| 50 |
up and ensure that it is working. Do note that setting one up is outside
|
| 51 |
the scope of this document.
|
| 52 |
|
| 53 |
2) Listhandler requires Mailhandler to be installed and configured first.
|
| 54 |
Both modules can be downloaded from the drupal.org website from
|
| 55 |
http://drupal.org/project/mailhandler and
|
| 56 |
http://drupal.org/project/listhandler
|
| 57 |
If you have not, please download them and extract the contents of
|
| 58 |
the archives into your modules directory.
|
| 59 |
|
| 60 |
3) Within your Drupal website, enable the Mailhandler and Listhandler modules
|
| 61 |
in Administer -> Site building -> Modules.
|
| 62 |
N.B. Please enable Mailhandler first, otherwise Listhandler will fail to
|
| 63 |
enable cleanly.
|
| 64 |
In the same section, please ensure that the Forum and Comment modules are
|
| 65 |
also enabled.
|
| 66 |
|
| 67 |
4) Create a forum that you wish to be the repository for your list's messages.
|
| 68 |
Administer -> Content management -> Forums -> Add forum
|
| 69 |
Enter a name, description and set the Parent (leave as "<root>" if unsure)
|
| 70 |
and click on "Submit".
|
| 71 |
In the listing, click on the forum name you just created. Make a note of the
|
| 72 |
URL you are sent to. The number at the end of the URL is the 'TID' (Topic
|
| 73 |
IDentification). You will need this later.
|
| 74 |
|
| 75 |
5) Configure a mailbox
|
| 76 |
Within your Drupal website go to Administer -> Content management ->
|
| 77 |
Mailhandler
|
| 78 |
Click on "Add mailbox"
|
| 79 |
In the form presented, set the values as indicated:
|
| 80 |
E-mail address:
|
| 81 |
Email address subscribed to mailing list. This should be the address
|
| 82 |
associated with the mailbox configured below,
|
| 83 |
e.g. my-subscribed-mailbox@example.com
|
| 84 |
|
| 85 |
Second email address:
|
| 86 |
Email address of the mailing list, e.g.
|
| 87 |
my-mailing-list-address@example.com
|
| 88 |
|
| 89 |
Folder:
|
| 90 |
This is the folder for my-subscribed-mailbox@example.com
|
| 91 |
Set this to "INBOX" (without the quotes) unless another value is
|
| 92 |
more suitable for your environment.
|
| 93 |
|
| 94 |
POP3 or IMAP Mailbox:
|
| 95 |
This is the protocol used to connect to
|
| 96 |
my-subscribed-mailbox@example.com
|
| 97 |
Pick which ever suits your environment. Choose POP3 if unsure.
|
| 98 |
|
| 99 |
Mailbox domain:
|
| 100 |
This is the full name of the email server containing
|
| 101 |
my-subscribed-mailbox@example.com
|
| 102 |
Talk to your service provider if you are unsure.
|
| 103 |
|
| 104 |
Mailbox port:
|
| 105 |
Set this to 110 for POP3 or 143 if using IMAP.
|
| 106 |
Other port numbers can be used depending on your mailserver
|
| 107 |
configuration.
|
| 108 |
|
| 109 |
Mailbox username:
|
| 110 |
This is the username for the my-subscribed-mailbox@example.com mailbox
|
| 111 |
|
| 112 |
|
| 113 |
Mailbox password:
|
| 114 |
This is the password for the my-subscribed-mailbox@example.com mailbox
|
| 115 |
Please note that this is stored as plain text. Please don't use something
|
| 116 |
sensitive.
|
| 117 |
|
| 118 |
Extra commands:
|
| 119 |
Leave blank unless you run into problems.
|
| 120 |
A common value is "/notls", without the quotes.
|
| 121 |
|
| 122 |
Mime preference:
|
| 123 |
Set this to: HTML
|
| 124 |
|
| 125 |
Security:
|
| 126 |
Set this to: Disabled
|
| 127 |
|
| 128 |
Send error replies:
|
| 129 |
Set this to: Disabled
|
| 130 |
|
| 131 |
From header:
|
| 132 |
Set this to a common header always present in emails sent by your mailing
|
| 133 |
list software.
|
| 134 |
|
| 135 |
Default commands:
|
| 136 |
Set this to the following three lines:
|
| 137 |
tid: 123
|
| 138 |
status: 1
|
| 139 |
|
| 140 |
Where 123 is the numeric taxonomy id of the forum you created in step 4.
|
| 141 |
The line "status: 1" sets the created node/comment as published.
|
| 142 |
|
| 143 |
Signature separator:
|
| 144 |
Set this to "-- ", without the quotes.
|
| 145 |
(Yes, there is a space at the end)
|
| 146 |
|
| 147 |
Delete messages after they are processed?
|
| 148 |
Check this option
|
| 149 |
|
| 150 |
Cron processing:
|
| 151 |
Set this to: Enabled
|
| 152 |
|
| 153 |
Input format:
|
| 154 |
(Click on "Import format:" to expand the section)
|
| 155 |
Leave the default as "Filtered HTML", unless you have another preference
|
| 156 |
|
| 157 |
|
| 158 |
6) Repeat steps 4 to 5 for each forum/mailing list you wish to configure.
|
| 159 |
|
| 160 |
|
| 161 |
7) Configure permissions
|
| 162 |
Within your Drupal website, allow authenticated users to post to forums:
|
| 163 |
Administer -> Roles
|
| 164 |
Against "authenticated user", click on "edit permissions"
|
| 165 |
Under "Forum module", check "create forum topics" and "edit own forum
|
| 166 |
topics"
|
| 167 |
Click on "Save permissions" (at the bottom of the page)
|
| 168 |
|
| 169 |
8) Configure Listhandler
|
| 170 |
Within your Drupal website go to Administer -> Content management ->
|
| 171 |
Listhandler
|
| 172 |
|
| 173 |
In the form presented, set the values as indicated:
|
| 174 |
Admin address:
|
| 175 |
This is the email address used by Drupal to send forum posts made by
|
| 176 |
anonymous users to mailing lists. Set this to "anonymous@example.com"
|
| 177 |
or similar and subscribe it to your mailing lists. Set this user to not
|
| 178 |
receive posts or otherwise it might be unsubscribed.
|
| 179 |
|
| 180 |
Strip title:
|
| 181 |
Vales to be stripped from email subject lines, before posting them as forum
|
| 182 |
topics/comments. Make sure to include any mailing list prefixes, like "[my-
|
| 183 |
list]". Separate multiple values with commas.
|
| 184 |
|
| 185 |
Account status:
|
| 186 |
When mailing list users post, Listhandler creates an account for them on
|
| 187 |
your Drupal site. You can configure these account to be Blocked or Allowed
|
| 188 |
when created.
|
| 189 |
Set as "Allowed" if you want those people to be able to log on to your
|
| 190 |
Drupal site. Set as "Blocked" if you don't.
|
| 191 |
|
| 192 |
Attachments as link:
|
| 193 |
Send attachments as links instead of MIME attachments. It affects only
|
| 194 |
mails generated by forum posts.
|
| 195 |
N.B. You will need to have the Upload module enabled and allow users to attach files to forum posts
|
| 196 |
|
| 197 |
Mailing list and Prefix
|
| 198 |
For each mailing list configured, you can set the [prefix] title that the
|
| 199 |
mailing list software appends to the subject line of each email. Set it
|
| 200 |
here to help Listhandler pick the right forum that posts should go to.
|
| 201 |
It is also recommended that you set "Strip title" to include mailing list
|
| 202 |
prefix as well.
|
| 203 |
|
| 204 |
|
| 205 |
9) For each configured mailbox, subscribe it to the appropriate mailing list.
|
| 206 |
|
| 207 |
|
| 208 |
Testing and troubleshooting
|
| 209 |
===========================
|
| 210 |
|
| 211 |
All being well, you won't have any problems. But if you do, here's some helpful
|
| 212 |
troubleshooting techniques:
|
| 213 |
|
| 214 |
1) Mail is only collected by Mailhandler whenever cron.php is run.
|
| 215 |
You can initiate a Cron run by going to http://www.example.com/cron.php
|
| 216 |
If you haven't setup a Cron schedule on your Drupal site, go to
|
| 217 |
http://drupal.org/getting-started/5/install/cron for help.
|
| 218 |
|
| 219 |
|
| 220 |
2) Ensure the mailing list is working as expected. Ensure that you are
|
| 221 |
subscribed and that posts you send to it, get sent back to you.
|
| 222 |
|
| 223 |
3) Use a webmail client, Thunderbird, Outlook or other email client to examine
|
| 224 |
the mailbox of "my-subscribed-mailbox@example.com".
|
| 225 |
Is it receiving posts from the mailing list?
|
| 226 |
Is there a subscription confirmation pending?
|
| 227 |
|
| 228 |
4) Examine the mailing list configuration to see if there are bounce emails from
|
| 229 |
"my-subscribed-mailbox@example.com".
|
| 230 |
|
| 231 |
5) Look at logs in Drupal: Administer -> Logs -> Recent log entries
|
| 232 |
to see if Mailhandler and/or Listhandler have any problems.
|
| 233 |
|
| 234 |
6) Examine your mailserver logs to ensure that emails are being received and
|
| 235 |
email is being collected from the mailbox successfully.
|
| 236 |
|
| 237 |
7) Confirm that you have
|
| 238 |
tid: <n>
|
| 239 |
in the Mailhandler configuration.
|
| 240 |
Without it Listhandler will not be asked to handle incoming emails.
|
| 241 |
|
| 242 |
|
| 243 |
Extended use
|
| 244 |
============
|
| 245 |
|
| 246 |
1) Add links for uploaded files:
|
| 247 |
a) Enable the Upload module, download and enable the Comment Upload module
|
| 248 |
b) Within your Drupal website go to Administer -> Content management ->
|
| 249 |
Mailhandler
|
| 250 |
c) Tick Attachments as link
|
| 251 |
d) Click on Save configuration
|
| 252 |
Please note that Listhandler doesn't work with modules that modify the path
|
| 253 |
that uploads are saved to. There is no plan to add this functionality.
|
| 254 |
|
| 255 |
2) Allow more HTML tags, but still protect your site:
|
| 256 |
a) Install the SafeHTML and UnWrap modules and enable them.
|
| 257 |
b) Create an Input filter called "Mailinglist Filter" through Administer ->
|
| 258 |
Site configuration -> Input formats.
|
| 259 |
c) Apply that to Mailhandler posts through Administer -> Content Management
|
| 260 |
-> Against <Mailbox name>, click "Edit"
|
| 261 |
d) Scroll to the bottom
|
| 262 |
e) Click on "Input filter" and select "Mailinglist Filter".
|
| 263 |
f) Click on "Update mailbox"
|
| 264 |
|
| 265 |
3) In step #2 of the main instructions you could set up a folder for each
|
| 266 |
mailing list instead of a mailbox for each one. However documenting such a
|
| 267 |
configuration is beyond the scope of this document and you are responsible
|
| 268 |
for testing it to ensure it works.
|
| 269 |
|
| 270 |
4) Allow users to post images that appear inline.
|
| 271 |
See http://www.venturacottage.com/adding-content-site-email for how to enable
|
| 272 |
Mailhandler to cope with attached images.
|
Parent Directory
| 
Revision Log
| 
Revision Graph