## Please edit system and help pages ONLY in the moinmaster wiki! For more
## information, please see MoinMaster:MoinPagesEditorGroup.
##master-page:Unknown-Page
##master-date:Unknown-Date
#acl MoinPagesEditorGroup:read,write,delete,revert All:read
#format wiki
#language en

<<TableOfContents>>

= E-Mail Configuration =
See also HelpOnConfiguration.

== Outgoing mails ==

In order to enable support for outgoing mails, you must specify the `From:` address with "`mail_from`".  Furthermore, you must enable a transport, either by SMTP (use "`mail_smarthost`" to enable it) or by sendmail (use "`mail_sendmail`" to enable it). If you use "`mail_smarthost`" and the server requires authentication, then set "`mail_login`", too. 

 mail_from:: This value is used for the "`From:`" and "`To:`" headers in the emails sent (the "`To:`" has email address privacy reasons, email is not really sent to this address, but we don't want to disclose any real recipient address).

 mail_smarthost:: This is the IP or domain name of an FOLDOC:SMTP enabled server. On a Unix host, you can try to use `localhost`; on a Windows machine this will normally be a machine in your LAN or some host of your ISP.
 mail_login:: This is only needed when you use `mail_smarthost` and a server that requires SMTP AUTH to send mail; in that case, set this to the username and password separated by a space, i.e. `"user pwd"`.

 mail_sendmail:: This is a local command to run to send a message.  If set to e.g. '/usr/sbin/sendmail -t -i', use this sendmail command to send mail.  This is only useful on machines that have a mail transport agent installed.

== Incoming Mails (new in 1.6) ==

If you want to import mails to your MoinMoin wiki, i.e. allow it to receive and store the mails, you have to setup a few things.

First you have to setup your mail server to pipe every new mail into MoinMoin. The command  is `moin xmlrpc mailimport`. Note that you can use the parameter `--config /path/to/dir` to supply the path to a directory with a suitable MoinMoin configuration file. Then you have to ensure that there is a file called `mailimportconf.py` in that directory. It has to look like this (there is a sample file shipped in `wiki/config`): {{{
# This secret has to be known by the wiki server
mail_import_secret = u"foo"

# The target URL
mail_import_url = u"http://localhost:81/?action=xmlrpc2"
}}}

The secret is used to let the script authenticate itself at the wiki. The URL consists of the regular wiki URL and `?action=xmlrpc2`.

Now you can configure the wiki. There are the following configuration options:

 mail_import_wiki_addrs:: A list of e-mail target addresses of e-mails that should go into the wiki. MoinMoin searches for these addresses to know the target pagename, it should match the address that is known to the mail server. If you use some kind of forwarding mechanism, please put the address(es) your wiki users use to address the wiki ''first'' into that list and the address(es) you forward the e-mails to ''after'' that.

 mail_import_secret:: The secret that matches the `mailimportconf.py` configuration file. See above.

 mail_import_subpage_template:: This is the template for the pagename generated by the mail import code. See below for supported placeholders.

 mail_import_pagename_envelope:: The default value of this setting is `u"%s"` and that just means "use the pagename unmodified". You could also configure it to be `u"+ %s/"` which would add a plus and a blank char in front of what we got and a slash char after what we got from the mail subject or target addr. This is to save your users some typing if you ever want the behaviour triggered by the plus and the slash.

 mail_import_pagename_search:: Where (and in what order) to search for the target pagename, default is `['subject', 'to', ]` to first look into the subject and then (if we didn't find anything there) to look into the target addresses.

 mail_import_pagename_regex:: The pattern (regex) we search in the subject line for determining the target pagename, default is `r'\[\[([^"]*)\]\]'` which simply looks for something like `[[Target Page Name]]` (same as freelink syntax).

After you have configured the settings explained above, you should be able sending yourself mails. The actual usage is explained below.

= E-Mail Features =

MoinMoin currently offers two email-based services, which are explained in the following sections.

== Sending Login Data ==

If emailing is available, the UserPreferences dialog is expanded with a field "<<GetText(Your email address)>>" and a button "<<GetText( Mail me my account data )>>". The user can enter the email address he provided at registration and then gets an email containing all necessary data to re-login, after clicking the button.

== Change Notification ==

Any user can subscribe to changes of wiki pages by either clicking on the envelope icon <<Icon(subscribe)>>, or by adding a regex to the "Subscribed wiki pages" field of his UserPreferences. The system then sends, whenever a page is changed and the author doesn't uncheck the "<<GetText(Send mail notification)>>" checkbox, an email with the author, a link to the page, and the diff of the change. The author does not get notified of his own changes.

== Receiving mails (new in 1.6) ==

MoinMoin is able to receive mails. Mainly, you need to know what the e-mail address of the wiki is and send a mail to it. If you supply the target pagename before the wiki address (typing `MyWikiPage <wiki@example.com>` for example), you will get your mail into the wiki quite easily. There are a few rules for your mail:

=== From ===
We check the From: header if it is from a valid wiki user. Of course this is no real security, but maybe better than nothing.

When we create a mail overview table, we use the email address part of From: to try to lookup a wiki user account with that email address. In case we find some, we will link to his homepage from the From: column of the table. If we don't find a matching user account, we just list the realname part in the From: column.

=== To / Cc ===
To: is (as usual) made of 2 parts, like `TEMPLATE <wiki@example.org>`. We use the "realname" part to make up the target page name template (can contain special chars, blanks etc.) and the email address part to get it to the right destination. The simplest form of a target page name template is just a pagename like WikiSandBox.

See the example for the 2 different modes of operation.

When we create a mail overview table, we process To: and Cc: for the To: column in the same way we do it for the From: column (see above). We do not include the address of the wiki server (and if we only have the wiki server email, we just display "-").

=== Subject ===
The page name template can also be extracted (and also removed) from the first occurance of mail_import_pagename_regex within the subject.

Examples:
{{{
Subj: [[Target page name]] will work if you put it either at the beginning or the end of the subject.
Subject: bla bla bla [[PageName/$date]]
}}}

The text of mails with such subject will be added to the pages
{{{
Target page name
or
PageName/2006-07-20T14:48:27
}}}

The full subject will also be used to build the change comment, prefixed with "`Mail: `"; variables are not replaced there.

=== Mail body ===

The new page content is made from old page content (if any) plus the content of the email appended at the end. Page content will never get overwritten. Mails that are sent as `alternative` are shown with their HTML body on the page which is processed by a HTML parser.

E-Mail attachments will get put into page attachments under the page where the content will be put. Attachments will never get overwritten. The attachments will be linked from the content page (e.g. from a list of attachments at the end).

=== Generated content ===
If requested by a leading `+`-sign (e.g. `+ PageName/`), MoinMoin adds a table item to the parent page listing details about the e-mail.

=== Pagename generation ===
The placeholders `$from` (containing the name of the sender), `$date` (the date) and `$subject` (subject line) are supported.

The pagename is generated like explained below:
 1. Check if one of the mail target addrs (to, cc, ...) is in mail_import_wiki_addrs
 1. Process TO/SUBJECT in order as given by mail_import_pagename_search until we have found a pagename or have to give up:
   * Try to get the pagename template from the target addrs, or
   * Try to extract the pagename from the subject (explained above).
 1. If we didn't find a pagename, use mail_import_subpage_template as last resort.
 1. Apply mail_import_pagename_envelope to (optionally) extend the pagename.
 1. If the pagename ends with a slash, append the configuration setting `email_subpage_template` (see above) to the pagename.
 1. Expand the pagename template to get the actual pagename.
