Email Configuration

Out of the box, Sakai uses incoming mail to receive content that will be viewed using the Mail Archive tool, and to receive delivery failure notifications for outgoing messages. Outgoing mail is used for notification purposes, bug reporting, and to deliver content received by the Mail Archive tool.

You need to change a handful of settings within and outside of sakai to get mail working. Most of the changes are in sakai.properties, and will require you to stop Sakai, remove the sakai-mailarchive-james directory under webapps (but leave sakai-mailarchive-james.war), and then start Sakai again.

Outgoing Mail

For outgoing mail, you'll also need to set smtp.dns.1 and smtp.dns.2 to your DNS servers, and to set smtp@org.sakaiproject.email.api.EmailService to a host that handles SMTP in your environment. James can also handle outgoing mail for Sakai, but that this should only be used for small scale installations, as James will not provide the same level of robustness as a dedicated mail server. In particular, James will not handle delivery failures nicely, which makes it unsuited for a real deployment.

You'll probably also want to set setup.request so that informational messages either appear to come from a meaningful address (such as helpdesk@your.institution) or to clearly not come from a usable address (such as noreply@your.sakai.hostname).

You can make all the changes at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Outgoing Mail Using a Notification

The simplest way to test outgoing mail is to add a guest user to a site and enable notification:

Log in to Sakai as an administrator (or at least a site maintainer)
Navigate to a worksite
Open the "Site Info" tool
Click the "Add Participants" Link
Enter a valid email address that you have the ability to check under the "Guest(s) Email Address" heading (the lower text area), then click "Continue"
Select a site role (usually "access" or "maintain"), then click "Continue"
Tick the "Send Now" radio button and hit "Continue"
Click "Finish"

A mail message should have been sent to the email address you entered for the guest account.

Incoming Mail

To receive mail, you need to set smtp.enabled to true. You'll also need to set serverName to the service name of your installation (as in sakai.your.institution), so that James knows what messages it should field. You should also set serverId to the real hostname of the individual machine (or at least the unique part of it).

If you don't already have a mail transport agent (ala sendmail or postfix) and can bind to port 25, you should change smtp.port to 25. If you already have a mail agent, you'll need to find some way to move the appropriate mail from port 25 to 8025 (where james lives). You can use a NAT rule, or can configure sendmail or postfix to do the forwarding for you:

Sendmail Integration Instructions: http://bugs.sakaiproject.org/confluence/display/ENC/Sendmail+integration

Postfix Integration Instructions: http://article.gmane.org/gmane.comp.cms.sakai.devel/6139/

Postfix Integration Instructions Alternate: Postfix Email Configuration

Exim Integration Instructions: Exim Configuration

The following is a sample section of sakai.properties including all of the above changes:

# enable James
smtp.enabled=true

# configuring the port on which James listens.  In this example, another component (NAT rules, Sendmail) forward from 25 to 8025
smtp.port=8025

# James will only accept messages for this hostname
serverName=service.my.edu

# You'll get more meaningful feedback if you have the node name configured
serverID=node.my.edu

You can make these changes all at once, but you'll need to stop sakai, remove webapps/sakai-mailarchive-james/, and then start sakai again each time you want for changes to take effect in james.

Testing Incoming (and outgoing) Mail Using James

Once you get all that done and start Sakai, you should be able to test the your configuration as follows:

make sure James is listening on the right port
1. ```
telnet {the value you used for serverName} 8025 [or 25 if you've set it to that]
```
2. you should see a status message from the server indicating the server name and the MTA. The server name should match what you put in for serverId (plus a domain), and should be followed by something like
```
(James SMTP Server 2.1.3) ready {date and time}
```
Set up a site for testing the mail archive tool
1. Create a new site that includes the mailarchive tool.
2. Open the mailarchive tool in the new site. You should see the value of serverName as configured in sakai.properties.
3. Change the options for the mailarchive tool to accept mail from anyone (this makes it easier to test things).
4. Enroll a user in the test site with an email address you can monitor. Once this is done, you should get a copy of your test messages.
Test James from the command line using telnet
1. Connect to James using the port you set up above and a command like the following:
```
telnet {your hostname, or localhost} 8025
```
2. Now type:
```
EHLO {your service name, ala sakai.your.institution)
```
3. You should see a response like:
```
250 {serverID.domain} Hello {serverName} (localhost [127.0.0.1])
```
4. Now type:
```
MAIL FROM:<{your.email@your.institution}>
```
  and hit enter.
5. You should see a receipt like:
```
250 Sender <{your.email@your.institution}> OK
```
6. Now type:
```
RCPT TO:<{the email address you entered for the mailarchive tool in your site}>
```
  and hit enter.
7. You should see a receipt like:
```
250 Recipient <{email address for the mailarchive tool in your site} OK
```
8. Now type:
```
DATA
```
  and hit enter.
9. Now type:
```
Subject: test...
```
  (or something like that) and hit enter twice.
10. Now type the body of your message as in:
```
This is a message I am using to test James.
```
  When you're done entering the body of the message, hit enter twice.
11. Now hit enter, enter a single period, then hit enter.
12. You should see a receipt like:
```
250 Message received
```
13. Now type:
```
QUIT
```
  and hit enter.
14. Check the mailarchive tool to see if your message made it in.
15. If that doesn't work, go back and check your settings. The log files logs/catalina.out and sakai/logs/james-DATE may help figure out what's wrong.
If you have a separate mail transport agent (i.e. sendmail or postfix), try the same steps as above, but with the port for the MTA (25) instead of James.
Check to see that you've received a copy of the messages. If you haven't, check the logs and look for details in the returned message that will eventually be sent to the MAIL FROM: address you entered.

Delivery Failure Notifications

If you wish to receive delivery failure notifications, abuse notifications, etc. for mail sent from your Sakai installation, you should make sure that postmaster@{your service name} is a working email address. It is also advisable to set meaningful email addresses for the postmaster and admin users included with Sakai. If you are using James as a standalone mail server or forwarding all mail for your service host name to James, you may wish to configure an instance of the Email Archive tool to receive, display, and forward all mail for postmaster. By default, the alias "postmaster" is reserved (to prevent site maintainers from assuming that address). In order to set up an instance of the Email Archive tool to handle the postmaster address, you will need to manually remove the entry for the postmaster address from the sakai_alias table. You should then immediately add an instance of the Email Archive tool to a site of your choice (either the Admin Workspace or a dedicated site). Messages received for postmaster by James will then be viewable in the instance of the Email Archive tool you've set up. You should configure that instance of the Email Archive tool to accept messages from anyone.

Email Archive Tool Alias Naming Limitation

As noted above, Sakai includes a postmaster account for use by James. As a consequence, the alias "postmaster" is reserved and should never be used as an Email Archive Tool alias. Doing so will result in Sakai throwing a runtime error.

Documentation

Sakai Admin Guide - Email Configuration