Summary

The Advanced Email plugin gives you the ability to comment on blog posts, documents, reply to discussion thread, set your status and create discussion threads, documents, blog posts and tasks, all via email. By bringing the entire discussion to your desktop or mobile inbox you can participate in a manner both familiar and convenient, regardless of location or device.

End Users: once the plugin has been installed and configured appropriately (read the directions below before installing), you'll see an item added to the Your Stuff Menu called Mailing Lists. Clicking on this link will take you to a page that shows you all the spaces, projects, groups and blogs that you're either following or watching. You'll see a list of email addresses associated with each of those places: you can click on an email address if you want to test out the functionality. Type in a subject, add some text to the body of your email and click send. You should see the email show up as a discussion, document, blog post or task within a couple minutes.  Publishing via email is usually necessary when you don't have an internet connection, so if you'll probably want to add any of the email addresses that you think you'll use on a regular basis to your address book.

Administrators: installing the plugin via the admin console is the easy part; the plugin does require some additional work from you and potentially some cooperation from your IT department or from your hosting provider.  Read the installation instructions below for more information.

Screenshots

Coming soon!

Requirements

Clearspace 2.0.x or Clearspace 2.5.x.

Download

Download the plugin using the sidebar on the right.

Installation

1. IMPORTANT: This plugin requires that you have either a) deployed Clearspace to a server where the DNS A record of the server doesn't have a corresponding MX record or b) deployed Clearspace to a server where the DNS A record of the server does have a corresponding MX record and so you've created a separate DNS A record specifically for this email functionality. Additionally, it requires that you open inbound connections to port 25 and then use iptables to forward inbound requests on port 25 to port 2500 (or another port that is not a priveleged port). Here are some example configurations:

2. 1. Clearspace deployed to jivesoftware.com/community.  Because the DNS A record for 'jivesoftware.com' already has a corresponding MX record that handles mail for mail for the employees of jivesoftware.com, you'll need to create a separate DNS A record such as 'community.jivesoftware.com' which points to the same IP address as the server that Clearspace is deployed on and then (optionally) create an MX record that points to the A record 'community.jivesoftware.com'.  If you don't create an MX record, email transfer agents use the A record as a fall back (this is sometimes called an implicit MX record).

   2. Clearspace deployed to community.jivesoftware.com. It's unlikely that an MX record exists for the DNS A record community.jivesoftware.com so you most likely don't have to add or configure any DNS records. Mail transfer agents will first attempt to look up an MX record for community.jivesoftware.com, if they don't find one then they'll use the 'implicit' or 'fallback' A record.

3. As mentioned above, you'll need to make sure that Clearspace is able to receive mail on port 25 on the server it's deployed on. Ports 1024 and below are considered priveleged ports on Unix systems and so you'd have to run Clearspace as root if you wanted to bind to port 25, which isn't recommended. Instead, the plugin will by default attempt to bind to port 2500, which means you'll want to configure inbound requests on port 25 to forward to port 2500 using iptables. Here is a sample iptables command to forward requests on port 25 to port 2500:

> iptables -t nat -I PREROUTING -p tcp --dport 25 -j REDIRECT --to-ports 2500
> /sbin/iptables-save

It's also possible to have your existing mail servers forward mail to Clearspace.

• Qmail: Create a file under /var/qmail/control named smtproutes and with the content: domain.com:[IP MACHINE]:PORT where IP MACHINE would be something like 127.0.0.1 and port would be 2500. and then restart Qmail.

• Sendmail: 1. Add your domain to access file: DOMAIN.COM RELAY 2. Add a mailertable in mailertable file: DOMAIN.COM smtp:[IP]:PORT 3. Rehash the files: makemap hash /etc/mail/access < /etc/mail/access makemap hash /etc/mail/mailertable < /etc/mail/mailertable

• Exchange / IIS: 1.) Modify the Default Recipient Policy by adding your subdomain (i.e. community.jivesoftware.com) as a new non-primary address. Ensure that "This Exchange Organization is responsible for all mail delivery to this address." is unchecked for the new address. a. If prompted to change all address, choose no. 2.) Create a new SMTP Connector choosing "Forward all mail through this connector to the following smart hosts, providing the IP address of your SubEtha List Server as the address (i.e. 192.168.1.100) a. Add your local SMTP Virtual Server as a bridgehead server b. Select the Address Space tab and add a new SMTP address of your subdomain (community.jivesoftware.com). You can leave the cost at 1 and ensure that "Allow messages to be relayed to these domains" is checked.

1. Build and deploy the plugin.

2. Go to the Clearspace Admin Console and create the following system properties:* plugins.advancedemail.host: the DNS name of the server this plugin will run on. The value of this property should match the DNS A record that you configured in step one above.

• plugins.advancedemail.port: the port number that this plugin will bind to. By default the plugin will attempt to bind to port 2500.

• plugins.advancedemail.maxconnections: the maximum number of connections that the email server will allow. By default the plugin will accept up to 1000 connections.

1. Once you've completed the above steps, you're ready to test out the email publishing functionality.  Open a browser window and go to your Clearspace instance. Click on 'Your Stuff' and then on 'Mailing Lists'.  Create an email publishing alias for a space / community or a blog. Click on the resulting email link: your email client should open. Type a subject and a body, optionally add an attachment and then click send. After a few moments (depending on the speed of your network), you should see the document, discussion thread or blog post created in your Clearspace system.

How To Build

The Ant build.xml file at the root of the plugin includes a build.plugins target you can use to compile the code and package it into a JAR file. There's also a deploy.plugins target that copies the JAR into the <jiveHome>/plugins directory that accompanies your Clearspace distribution. Paths into your test Clearspace distribution assume that this plugin project is in the standalone Clearspace distribution at: <root>/plugins/plugins/helloworld.

Be sure to update the targets if you're testing another way, such as with the Clearspace WAR distribution.

Be sure to read the notes below about dependencies. The JAR files you'll need are included as part of Clearspace.

FAQ

• Q: Why can't you use an existing email server like the 'reply via email' feature already in Clearspace?

• • A: The existing 'reply via email' feature could be extended to other content types like documents and blog posts, but it would break down when you tried to create content.  Instead of creating a single account, this plugin acts as an email server and a like an HTTP filter. It looks at the sender email address and the recipient email address and confirms that a) the sender exists as a user in Clearspace and that b) the recipient is a named alias (much like an HTTP resource) and that c) the named alias was created specifically by the recipient. If any of the aforementioned conditions are false, the email is dropped.

• Q: Will this plugin allow spammers to relay?

• • A: No, the plugin only receives email, it doesn't send email. If you have an existing email server (like sendmail) installed on the same machine as Clearspace, you'll probably want to configure it to bind to another port and then configure Clearspace to send email on that new port.

If you'd rather deploy the plugin manually, you can do that in one of two ways:

• Just copy the plugin JAR file into the <jiveHome>/plugins directory. Your running Clearspace instance will deploy it automatically.

• Open the admin console and navigate to System > Settings > Plugins, then browse for your plugin JAR file.

Copyright and License

Copyright 2008 Jive Software Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.