- Project tools
- How do I...
|Over 500 more tools...
SubEtha Administration Guide
This document assumes you have read and understood the
If you are familiar with mailing list managers, SubEtha should be easy
to master. The basic ideas are that:
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
Mailing lists are created by Site Administrators.
The list creator decides two critical pieces of information:
The mailing list email address, which must be unique on the site.
The entire address (including domain) is significant; thus
email@example.com and firstname.lastname@example.org are different
lists. Of course, DNS MX records must actually route this mail to
the host that SubEtha is running on.
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:
Note that users who are not permitted to view list archives will
not be displayed the View Archives menu item.
- 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.
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:
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.
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.
The poster subscribes the email address with a new account and
the default role for the mailing list has POST permission.
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.
- SubEtha intelligently handles bounce messages using
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:
- Every EmailAddress has a bounceCount.
- 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
- When a bounce is received, the bounceCount is
incremented by two (at most once per 24 hrs).
- 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
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.