SubEtha Administration Guide

This document assumes you have read and understood the Install Instructions.

Concepts

If you are familiar with mailing list managers, SubEtha should be easy to master. The basic ideas are that:

User Accounts

• User accounts are created by subscribing to a mailing list with an email address.
• Each user account can have multiple email addresses.
• Each user account can have subscriptions to multiple lists, and designate which email address each list will deliver to.
• If a user is subscribed to a list (and has permission to post), email from any email address associated with that account will be accepted to the list.
• If a user with an existing account adds an email address that is already associated with another account, the two accounts are automatically and intelligently merged into a single account.
• Any time a user wishes to add a new email address to their account (either manually or by subscribing to a mailing list), a roundtrip confirmation using a token is required.
• Confirmation tokens are completely stateless; no changes are made on the server until the token is confirmed. If a token is lost or sent to the wrong address, simply repeat the add/signup process.
• Some accounts are designated as Site Administrators. In addition to the ability to create mailiing lists, site administrators have full permissions on all mailing lists.
• Only Site Administrators can grant or revoke the Site Administrator privelage.

Mailing Lists

• Mailing lists are created by Site Administrators.
• The list creator decides two critical pieces of information:
  1. The mailing list email address, which must be unique on the site. The entire address (including domain) is significant; thus announce@yourdomain.com and announce@otherdomain.com are different lists. Of course, DNS MX records must actually route this mail to the host that SubEtha is running on.

  2. The "official" public URL to the list's website, e.g. http://www.yourdomain.com/se/list/announce. This URL must contain the special context path "/se/list/" but is otherwise entirely arbitrary. Of course, any URL you use must actually resolve to SubEtha.

• Mailing lists have an arbitrary set of Roles, each of which have permissions such as POST and EDIT_FILTERS. The list owner decides what roles exist and what permissions they have. A permission is always relative to a list.
• Each list has a special Owner role which has all permissions on the list. The Owner role cannot be deleted or modified. Thus, at minimum, all lists have at least this one role.
• The list owner designates one role which will automatically be assigned to new list subscribers. This is the "default" role.
• The list owner designates one role which will be the effective role of any users who have not logged in. This is the "anonymous" role.
• To make it clear by way of example, a user visiting the archives page for a mailing list will be allowed to view the archives only if at least one of the following conditions is true:
  • The user is logged in and the user is a site administrator.
  • The user is logged in, the user is subscribed to the list, and the user's subscription role has permission VIEW_ARCHIVES.
  • The user is not logged in and the special "anonymous" role has permission VIEW_ARCHIVES.
  Note that users who are not permitted to view list archives will not be displayed the View Archives menu item.

Moderation Holds

• List owners can configure a mailing list to hold all subscription requests for manual approval. When a subscription request arrives, notification is sent to all users who have permission to APPROVE_SUBSCRIPTIONS.
• Arriving messages can be held in two ways, HARD and SOFT.
  • HARD holds require explicit moderator (anyone with APPROVE_MESSAGES permission) approval from the website. Only filters can trigger this type of hold, and moderators are notified via email when the message is held.
  • SOFT holds occur when mail arrives to a list from an email address that does not have POST permission (ie, the address is associated with an account that lacks the permission or the address is not associated with a subscribed account and the special anonymous role for the list does not grant POST permission). SOFT holds can potentially be self-moderated in one of two ways:
    1. The email address is added to an account that is already subscribed, and that subscribed account has a role with POST permission. This would be the case when a subscribed user posts from a new email address, then adds the new address to their account.
    2. The poster subscribes the email address with a new account and the default role for the mailing list has POST permission.
    Note that moderators are not notified via email about SOFT holds. Typically SOFT holds are spam. The poster is given sufficient instruction to properly self-moderate the hold (ie, subscribe to the list). In addition, as of v0.8, no more than one "you must wait for admin approval" email per day will be sent to the poster. This will help prevent 'backscatter' related to spam.
• There is no specially designated "moderator" account. You either have the APPROVE_MESSAGES/APPROVE_SUBSCRIPTIONS permissions or you do not. List owners who wish to create special moderator-only accounts can create a "Moderator" role with only that permission; in fact several of the blueprints do exactly this.
• Generally speaking, moderators should check for subscription holds and ignore message holds (which will usually be spam). Non-spammers can self-moderate their own messages.

Bounce Processing

• SubEtha intelligently handles bounce messages using VERP'd envelope senders. This removes the need to attempt to parse bounce messages from servers.
• The envelope sender is VERP'd and thus bounces cause the bounceCount to increment faster than decrement.
• Things work like this:
  1. Every EmailAddress has a bounceCount.
  2. When a mail is sent from a list to an EmailAddress, the bounceCount is decremented by one (at most once per 24 hrs, even if multiple mails are sent within that period).
  3. When a bounce is received, the bounceCount is incremented by two (at most once per 24 hrs).
  4. The EmailAddress is removed from all lists (by setting subscription to "No Delivery") when the bounceCount reaches a threshold which is currently hard coded as 7.

Programming

• SubEtha is a true three-tiered application. Nearly everything you can do from the website can be automated using the remote EJB interface. This interface is fully contained in core-api.jar.
• SubEtha offers two kinds of plugins:
  • Filters manipulate email either as it arrives or as it is sent (or both). Each filter defines a set of configuration parameters that list owners can set on a per-list basis.
  • Blueprints initialize a new mailing list with a set of configuration options. This includes basic settings, enabled filters, filter arguments, roles, and permissions. No matter what blueprint a list is created with, list owners are free to reconfigure the list afterwards.
• Plugins are hot-deployable as JBoss services. SubEtha gracefully handles filters that have been enabled on lists but are subsequently removed from the JBoss instance - even at runtime.
• Plugins run inside the SubEtha JVM and run with site administrator privelage. Techncially this means they can do almost anything. We recommend you stick to the APIs in core-api.jar; any other API is considered internal and highly likely to change without notice.