Voting starts in March for the Drupal Association Board election.
On this page
- Installing Drupal
- Enabling the required modules
- Configuring the Mailhandler module
- Testing the Mailhandler module
- Setting up messaging
- Setting up notifications
- Configuring the Mail Comment module
- Creating a forum
- Testing the Mail Comment module with the forum
- Altering message templates
- Configuring cron to run automatically
- Caveats and issues with this tutorial
These instructions explain the process of installing and configuring Mail Comment to create online forums that allow full inbound and outbound email participation. Participants receive copies of new forum posts by email, and if they reply to the emails, the replies are posted to the forum. The result is a forum that doubles as a Listserv.
For this walkthrough, we will start with a freshly installed portal of Drupal 6.13. To start off, all I have done at this point is to log in as Admin, go to Administer> Site Information, and give the site a name ("email-forum portal") and a real email address.
Enabling the required modules
In that Drupal installation, download the following modules (in this case, using those modules that were current as of November 2009):
- Mailhandler 6.0-1.8
- Messaging 6.x-2.2
- Notifications 6.x-2.2
- Mail Comment 6.x-1.0-beta4
- Token 6.x-1.11
Enable these modules at Administer > Site building > Modules:
- Simple Mail
- All of the modules in the Notifications group except for Notifications Lite.
- Mail Comment
Configuring the Mailhandler module
The next step is to configure the Mailhandler module and create an entry for the mailbox that you will use. In other words, telling mailhandler about the existing email address that the system will use for people to mail their posts IN to the system.
- You must go and create an email box on a mail server that will serve as the box for these posts to be sent into the system. For the purposes of this walkthrough, I created an email box on an inexpensive hosting service called BlueHost, which, like many hosting companies, allows you to create email accounts on the domains they host. Note also that I am choosing to use the IMAP protocol for connecting to the account, and I am choosing to use SSL (I believe that my drupal hosting company is only allowing this kind of connection to be made when SSL is used.)
- Go into that email account that you created, and delete all emails that might be sitting in the inbox by default.
- In your Drupal portal, go to Content > Mailhandler mailboxes
- Click Add Mailbox.
- Here enter all the information about the email account that you created. See illustration below. The below entries are for my example email@example.com account - naturally, replace the entries with your own. Leave all entries untouched except for these:
- In "email address," I enter the account's email address: firstname.lastname@example.org.
- For "Folder," I leave it untouched, as "INBOX."
- For "POP3 or IMAP Mailbox," I choose IMAP.
- In "mailbox domain" give the domain of the mail server, in my case box473.bluehost.com
- In "mailbox port" give the communication port that is used by the email server. In my case, since I am using IMAP and using SSL, my hosting company instructed me that the port is 993..
- In "emailbox username," enter the username for logging into the email account. In my case, but not necessarily in yours, my provider has the email account logged into by using the full email address but substituting + for @: therefore, I use emcollab2+localdev.net
- In "mailbox password" type the password that you had given for that email account.
- In "extra commands," you will usually only need to enter these additional commands for the email call in some circumstance, for instance if you are using SSL. I am using SSL, so I enter: /ssl/novalidate-cert
- Make sure that "delete messages after they are processed" remains checked.
- Make sure that "Message authentication method" is set to "MailComment Default". Otherwise, mailcomment will not authenticate the message and will tell the user that there was an error.
- Save these settings. To see an image of how my mailhandler configuration looked, click here.
- Though you have just saved them, you now want to test to see if the portal is able to connect to the email account with these settings, so choose Edit for that mailbox once again, and at the very bottom click the Test Connection button. Ideally the portal will display the message: "Mailhandler was able to connect to the mailbox."
- TROUBLESHOOTING: If you got errors or the system hangs for a long time, then carefully check all the settings, and also consider if your servers or host are blocking the ports or protocols, requiring you to choose a different arrangement for POP/IMAP or a different decision about using SSL.
Testing the Mailhandler module
Optional step: Testing the function of Mailhandler's function by using your new Mailhandler mailbox to submit stories to your portal by email.
NOTE: This step is not required. It is good to do it if you are interested in better understanding the functionality of the Mailhandler module, or if you are trying to be extra careful about confirming that each of the parts of Mail Comment are working at this point in the installation:
- Since you have your Mailhandler mailbox configuration set up correctly now, we will experiment with it by setting up your portal so that when a registered user of the portal sends an email to the email address, the email is automatically converted to a Story, posted on the site, and promoted to the home page.
- Because this function will only accept emails when they are emailed from an email address that is that of a registered account on the portal: Go to the admin account that you have been using on the account, and ensure that the email address associated with "admin" is your own email address.
- Go to Messaging & Notifications > Mail Comment and select turn on Passthru to mailhandler module, also set here the default mailhandler authentication during passthru to Mailhandler Default. This will prevent error messages for new posts submitted via email that do not include the authentication string that MailComment looks for. Failing to do this will result in authentication error emails as described at http://drupal.org/node/539166#comment-2085114.
However if you will only use mailcomment for replies to posts online, then you can set this to off. It seems some people have found that without setting this to off, their messages are always posted as new messages rather than replies.
- Go to Mailhandler and edit the mailbox that you created. Find the entry for Default Commands. Into that box, type the following commands, each of the three on a new line. These tell Mailhandler that with an incoming email, make it into a story, set it to promote to home page, and set it to published (i.e. a status of 1):
- Now, emailing from the email address that you earlier set to be the email for the portal's admin account, send an email to the email address of the mailbox that you configured, with a subject of "Spring picnic a universal success" and a body of "Our club's Spring Picnic was hailed by all as the best in years."
- Once you have sent that email, we know that the email is sitting in the emailbox of the mailbox. Definitely don’t go check that account's email, which might mark the message as "read." Instead, go to mailhandler, and in the line next to your mailbox, click the "Retrieve" link.
- You should see a progress bar and the email will be read from the email account, processed by mailhandler, and deleted from the email account (since you configured it to do so earlier.)
- Now, provided that your site's home page has not been changed to something other than simply "node" (you can check that at the Site Information page) -- the next time you visit your site's home page, there should be your new story promoted to the home page.
- TROUBLESHOOTING: Didn't work? Check to make sure that you entered the three commands correctly, and make sure that the email address that you send the story in from is indeed set as the email address of the admin's portal account. Also, make sure you didn't type something into the mailbox configuration entry for "From header." That should be blank, because then Mailhandler will look in the incoming email's "from" line to get the email address that will determine which portal user should have the new story attributed to them.
- Important: In the above step you have experimented with and tested mailhandler's ability to submit stories via email. Now we want to disable that function -- we are not here to set up email story submission but to set up Mail Comment. So, go to Mailhandler, edit the mailbox that you created, and go to the entry for Default Commands. Delete everything in that box and Save the changes to your mailbox configuration.
Setting up messaging
- Go to administer > messaging & notifications > messaging settings.
- Under "Default send method," click "Mail" and click Save Configuration.
- Then click the send methods tab, and make sure that for the different send methods, the filter that is specified is "Messaging plain text."
- Again click "Save configuration."
Setting up notifications
- Go to Administer > Messaging & Notifications > Notifications settings.
- Check the boxes for "Notify poster of own posts." Leave "immediate sending" un-checked.
- Under "Default send interval," choose "Immediately." This is different from the "immediate sending" check box higher on the page, which you left un-checked.
- Click "Save configuration."
- Click on the Content Subscriptions tab. This is where we specify which types of content can be "email-subscribed" to. The only change for this page is to uncheck the check box next to "Author," since we won't be offering subscriptions that way. Only "Thread" and "Content type" should be checked. Click "Save Configuration" at the bottom.
- Click on the "User Interface" tab. In "Visible subscription types," uncheck "Author" and at the far bottom click "Save configuration."
- Now we need to change a couple of permissions so that authenticated site users have the ability to "subscribe" to content and maintain their subscriptions. Go to Administer > Permissions and:
- in the section for Notifications module, check the "authenticated user" column boxes for "maintain own subscriptions" and "manage own subscriptions."
- in the section for Notifications_content module, check the "authenticated user" column boxes for "subscribe to content" and "subscribe to content type."
Configuring the Mail Comment module
- Go to Administer > Messaging & Notifications > Mail Comment.
- Under Mailhandler Inbox, ensure that the mailhandler inbox that you configured is chosen.
- Leave expiration time set to Never.
- You can leave "Server string for message ID" as "example.com."
- Leave Message Cleaner set to "off."
- For "Mail Comment Content Types," choose "Forum Topic."
Creating a forum
This forum is where the email-enabled discussion will take place, for the purposes of this documentation. When your system fully works, you may instead choose to have Mailcomment work in some other part of your site.
- Ensure that the Forum module is in fact enabled. Go to Administer > Modules, find "Forum," and check it (and any of the modules that it requires) and then click "Save configuration."
- Go to Administer > Forums. Click the "Add forum" tab. In "Forum name," give it a name of "Discussion Forum." Leave other entries unchanged, and click "Save."
- We want it to be easy to access this forum, so let's put the entry for this forum on a menu at the left. First, take note of the path of the forum that you just created, by clicking the link to that URL and seeing the end of the URL at the top, which is the path. In my case, the path is forum/1. So, go to Administer > Menus, click Add Menu, create a new menu called Main Menu, click Add Item, and have your new item have the path forum/1 and the name "Discussion Forum." Click Save Configuration, and lastly go to Administer > Blocks, and next to Main Menu, specify "Left sidebar," and click "Save blocks" at bottom. Your new menu, with the link to the forum, will appear in the left nav bar. Click your portal's name or logo at top to go to the home page, to get away from the strange blocks-preview screen.
Testing the Mail Comment module with the forum
Create a few test users, go the users you want to participate, and subscribe them to "Forum topic posts:"
- Go to Administer > Users and create a couple test user accounts, perhaps each with a different webmail account (Yahoo, Gmail, etc.) These will help you with testing and learning about the behavior and cosmetics of the posts in different email clients.
- Logged in as your admin account, go to My Account > Notifications tab > Content type sub-tab and put a check next to "Forum topic."
- To subscribe the other users that you created, you can either simply do them while still logged in as Admin, by going to administer > users, clicking the user's name, and going to Notifications tab, Content type sub-tab, and checking Forum Topic and saving. (Or, if one logs in to the portal as the actual user, they can go to My Account > Notifications tab > Content type sub-tab and put a check next to "Forum topic.")
Create a test thread and carry out a test conversation using the email-enabled forum.
- Log in as the administrator. Go to your discussion forum. Click the link to "Post new forum topic." Give it a Subject like "Home Decorating Tips and Tricks" and a body like "Have decorating ideas to share? Post them here!"
- The email notification of this new topic will not be sent out until Drupal makes its "cron" run. Later we will configure your portal to carry out its Cron tasks every five minutes, one minute, or whatever you prefer. However, while we are still testing, we will simply run Cron manually each time we want it to process incoming and outgoing emails. SO: Go to Administer > Status Report and click on the "Run Cron manually" link in the Cron section.
(Note: To make testing easier, you may want to create another entry in the Main Menu that you created earlier, with menu item's title being "Run Cron" and the path being: /admin/reports/status/run-cron … Then each time you need to run Cron to test the workings of the email, you can just click this link. In an actual live site you would not have this link visible, and you would have cron run periodically as we will later describe.)
- Now that you have just run Cron, an email should be sent out to all of the email accounts of the users that you subscribed earlier. The email may not be beautifully formatted. Later on you can use templates to determine the emails' appearance.
- TROUBLESHOOTING: Did the emails not arrive? Check very carefully over your configurations of the mailhandler email box, Mail Comment, notifications, and messaging. Did you have success with the optional test of mailhandler that we described above? Also, ensure that the test users you created have the correct email addresses set. Also look at the various permissions changes that we have made, and closely check that they were all done correctly.
- Go to one of the test users' email accounts, open the email that was sent from the portal, and hit Reply. Type a sentence or two as a reply, and hit send.
- Run Cron.
- Now that Cron has run, it should have:
- taken the reply that you just wrote, posted it into the Discussion Forum, attributed to the user that wrote it (this is made possible by recognizing the email address that sent the reply and matching it up with the user account in the portal -- if the "From" email address specified in the email sent in to the portal does not exactly correspond to a site account, Mail Comment should send an error email back and refuse to post the message.)
- sent this newly posted reply back out to the subscribed participants.
Altering message templates
You will probably want to modify the way that the emails are formatted, to suit the type of content and site you are working with:
- Go to Administer > Message templates.
- You will see that there are different templates for node creation, node updates, and node comments. The forum that we have just created makes heavy use of Node Comments template, but it also makes use of the Node Creation template when a new forum topic is created.
- Click Notifications for Node Comments. Open the four sections (Subject, Content, Digest Line) and you will see the areas where you can specify the text and spacing around the content elements that are mailed (which are specified with codes in square brackets.) In the Available Tokens section, you can see the full list of other bits of content that you can drop into the template to customize the emails' appearance.
Configuring cron to run automatically
- How you configure your cron to run at your chosen frequency (every minute, every five minutes, every hour, etc) depends on where you application is running. If your Drupal portal is running on a hosting server that offers you a "control panel" interface, you may find an entry called "Cron jobs" that allows you to easily specify the commands you want to be run, at what interval. If so, the command on my host to run the cronjob is: wget -O - -q -t 1 http://www.localdev.net/collab/cron.php;;
- If you aren't able to understand setting up Cron yourself, talk to the person or company that administers your server.
- When Cron is running automatically on a cyclical basis, then each cron run will fully process incoming and outgoing emails to your Mail Comment-enabled forums.
Caveats and issues with this tutorial
Please check the watchdog table and the mail messages for errors:
|watchdog||email to sender||solution|
|Received an email without signed parameters||The email you sent was rejected because there was a signature error.|
|Received an email with a expired signature||The email you sent was rejected because it was sent after the allowed response time for the original email.|
|Received an e-mail without a valid user id||The email you sent was rejected because we couldn't authenticate it.|
|Received an email with no parameters||The email you sent was rejected because there was a validation error.||- mailbox not set to 'mailcomment default'|