Field Guide to Programmers

Drupal’s mailhandler module allows you and your visitors to email new content into your site. This is a powerful module because it allows you to create any content whatsoever. In addition, with the application of another module named listhandler, you can turn your forums into a post-by-email community.

The mailhandler module is very powerful and so of course it is also poorly documented. This is my humble attempt at distilling what I have learned about the mailhandler module. It is by no means exhaustive.

Setup

To setup the mailhandler module, begin by downloading and installing the module as you would any other Drupal add-on. Once you have the mailhandler module code installed in your Drupal environment (i.e. ftp the mailhandler folder to drupal/modules), you’re ready to start configuring.

Creating an email address

To start with, you need an email account for mailhandler to check. mailhandler is capable of checking POP or IMAP mailboxes so either should be fine. When setting up your email account, there are three things to keep in mind:

1. You will be giving this email address out to your users.

2. You may end up creating more than one mailhandler.

3. Drupal stores the password in cleartext when you set up the account, so you may not want to use the same password or rubric you have for other critical passwords.

The first consideration is obvious: you want to create an email address that is fairly memorable. I’ll address the second consideration later on.

A word on Security

mailhandler has built-in security to protect your site from malicious and spam posts. First, it will only accept emails that come from registered users, using the email address to validate the sender.

If you are concerned about spoofing, you can also require users to supply their Drupal password in the body of their email. [I would also recommend setting up your mail server to enforce SPF records for inbound email, but this is probably a bit much for the casual site admin. Still, if you enforce SPF records for in-bound email you will eliminate most if not all spoofing attempts.]

Configuring the mailhandler

The mailhandler configuration is located under Administer->Content Management->Mailhandler.
Begin by clicking “Add Mailbox”. This will lead you to a long form of configuration options. I’ve replicated the list below:

E-mail address:
The e-mail address to which users should send their submissions.

Second E-mail address:
Optional. The e-mail address to which modules should send generated content.
[This is used by other modules within the Drupal engine to send outbound email. For example, if you have installed the listhandler module, this field would be used to keep your mailing list updated with the latest forum posts.]

Folder:
Optional. The folder where the mail is stored. If you want this mailbox to read from a local folder, give the full path. Leave domain, port, name, and pass empty below. Remember to set the folder to readable and writable by the webserver.
[This is useful if you have mail rules that sort incoming messages into different folders. It really depends on how you want to organize the mailhandler accounts, but I would probably favor setting up different addresses instead of fussing about with this.]

POP3 or IMAP Mailbox:
If you wish to retrieve mail from a POP3 or IMAP mailbox instead of a Folder, select POP3 or IMAP. Also, complete the Mailbox items below.

Mailbox domain:
The domain of the server used to collect mail.

Mailbox port:
The port of the mailbox used to collect mail (usually 110 for POP3, 143 for IMAP).

Mailbox username:
This username is used while logging into this mailbox during mail retrieval.

Mailbox password:
The password corresponding to the username above. Consider using a non-vital password, since this field is stored without encryption in the database.
[Yes, the password is stored in clear text.]

Extra commands:
Optional. In some circumstances you need to issue extra commands to connect to your mail server (e.g. “/notls”, “/novalidate-cert” etc.). See documentation for imap_open. Begin the string with a “/”, separating each subsequent command with another “/”.
[I needed to add the /novalidate-cert option as my mail server has a self-signed certificate. If that doesn't make a whole lot of sense to you, it might when you try to connect for the first time. ]

Mime preference:
When a user sends an e-mail containing both HTML and plain text parts, use this part as the node body.
[You should probably set this to HTML. Chances are some of your users will have an HTML mail client.]

Security:
Disable security if your site does not require a password in the Commands section of incoming e-mails. Note: Security=Enabled and Mime preference=HTML is an unsupported combination.

Send error replies:
Send helpful replies to all unsuccessful e-mail submissions. Consider disabling when a listserv posts to this mailbox.
[I think the suggestion of "consider disabling" is more of a requirement. Nothing says newbie like auto-responders to a listerv.]

From header:
Use this e-mail header to determine the author of the resulting node. Admins usually leave this field blank (thus using the From header), but Sender is also useful when working with listservs.
[This is an interesting feature. You can set this up to authenticate posts on any header in the email message.]

Default commands:
A set of commands which are added to each message. One command per line.
[This is very important. Using this field, you can set up automatic posting to forums, blogs, etc. This makes it easy for your users to post new content without going crazy with commands in the body of their email. Below I will show some of the commands you can use in this field or in the body of the email, but spend some time thinking about how you can make things easier for your users by utilizing this field.]

Signature separator:
All text after this string will be discarded. A typical value is “– ” that is two dashes followed by a blank in an otherwise empty line. Leave blank to include signature text in nodes.

Delete messages after they are processed?
Uncheck this box to leave read messages in the mailbox. They will not be processed again unless they become marked as unread.

Cron processing:
Select disable to temporarily stop cron processing for this mailbox.
[I kept this turned off while testing, but I suppose it wouldn't hurt anything to have it on.]

Input format
[This is the format for the inbound entries. I found this to be one of the more frustrating parts about mailhandler. Basically, you should be able to set this on the fly for each new post by including the directive in your message. Unfortunately, I couldn't get it to work. So, from my perspective, this is where you MUST set the format. If I figure out why this doesn't work for me, I will update this accordingly.]

The first run

Once you’ve set up the mailhander, you will end up back at the list of existing mailhandlers. Unless you’ve already been this way before, there should be one handler in the list. You can fire off the mailhandler by clicking on the “Retrieve” link. Try it out!
If everything worked, you should see some nice green text:

Mailhandler retrieve successful: 0 messages for xxxx@somesite.com

If not, check out the Extra Commands section above. Also, make sure you are accessing your mail server on the right port. POP runs on 110 by default, but some hosts change this for a variety of reasons.

Commands

The mailhandler module parses the body of your email message for commands and then for content. As noted in the configuration section above, you can define all the commands for inbound messages in the setup and absolve your users from the need to do anything other than write luscious prose.

Of course, you are a control freak and you want to micromanage each and every post you throw up there. So, you’ll probably put the commands in your email body anyway.

With that in mind, a basic list of controls appears below. I’ve cribbed these from a variety of places (including the source code), so your mileage may vary on usage. When in doubt, try it out. In your email body, list each control on a separate line followed by a colon and the value:

type: (values are: blog [default], story, page, forum, comment)

taxonomy: [SectionName] (categories for post, separate multiples with a comma. Also, this needs to be in brackets)

promote: (0 or 1. Use 1 to put the content on the front page)

status: (0 or 1. Use 1 to publish the content immediately)

comment: (0, 1, or 2. 1 is read-only comments, 2 is open comments, and 0 is no comments)

format: (1,2,3. 1 is Filtered HTML, 2 is PHP, 3 is Full HTML. Like I said above, I did not get this to work but I found a reference to “depends on your input filter settings” so I will try once more)

moderate: (0 or 1. 0 NOT in moderation queue. 1 in moderation queue)

revision: (0 or 1. 0 is no revision, 1 is a revision)

sticky: (0 or 1. 0 is not sticky, 1 is sticky at the top of the page)

title: (DO NOT USE THIS, use the mail subject only, if you use both, the title will be a combination of both subject and title like “Welcome ! Welcome !”)

path: (to set a URL alias)

References:
better documentation for nonprogrammer users
Drupal mailhandler Tutorial
Useful command for mailhandler default commands (make sure to read the comments on this post as the post itself is a bit cryptic)

Mailhandlers Galore!

If you think about it, I’m sure you’ll have ideas about how you might use mailhandlers to create lots of quick methods for posting content to your site. For example, I’ve been thinking about ways to archive automatic daily sales reports and other system generated emails into a huge archive of “what’s going on at work”. A few mailhandlers would make quick work of this…

Another example might be archiving emails from people I know in a personal Drupal site. I set up a few filters on gmail and forwarded messages are soon streaming into my website.

Then of course there is just the posting of content. Articles like this one for example!