EE Support: NPOGroups Administrators Guide

EE Support:
NPOGroups Administrators Guide

NPOMail
Users
Administrators

NPOGroups
Subscribers
Administrators

Web hosting
Basic Email
DNS

FAQ

Roles and privileges
Logging in
Creating groups
Adding subscribers
Posting messages
Accepting subscriptions from your Website
Message footers
Managing bounces
Deleting groups
Retrieving subscriber lists
Customizing templates
Including one group in another
Setting up NPOGroups Custom
Further reading

Roles and privileges

There are different types of privileged users (controlled from Manage Group -> Change Settings -> General):

All NPOGroups

List Owners: Default is the group's creator. List Owners can control everything about a particular group, including changing other owners or moderators, as well as approving or rejecting subscription requests on groups that require membership approval. Owners do not necessarily have the ability to post to a moderated or newsletter type group -- see Moderators.
Moderators: People designated as Moderators are granted posting privileges: they can post to newsletters or moderated lists and can approve or reject postings to moderated lists. The default is to treat all Owners as Moderators also, but if a group has any Moderators set, then these are taken to be the only people with posting privileges, and the other Owners will not have Moderator powers unless they are also listed as Moderators. Any person can be just an Owner, just a Moderator, or both.
Requesters: Controlled by request to Electric Embers. Requesters will see the Create Group button (normal users won't), and can submit a group request that will then have to be approved by a Listmaster.

Custom NPOGroups only

Listmasters: Controlled by request to Electric Embers. Listmasters in a Custom domain have full Owner-level access to all groups in their domain, and can create and close/purge groups as well. They also will approve or reject requests for new groups submitted by Requesters.

Logging in

In order to create or manage groups, you must log in to the NPOGroups system with an appropriately privileged address. If you have NPOGroups Basic, you log in at http://npogroups.org, while NPOGroups Custom will be under your own domain, usually like http://lists.your-domain.org, If you don't know your password, or lose track of it at any point, click Request Password. You can change your password by clicking Preferences.

You can also change your subscribed address under Preferences, but changing your email address there updates it only on all subscriber lists. It does not affect group ownership or moderators. To update your owner or moderator address, we suggest this procedure:

Log in with your old, recognized moderator/owner address.
Go to the owner/moderator editing page by clicking on Owners or Moderators in the list info box in the left menu.
Add your new address in addition to your old address.
Log out of NPOGroups, then log in with the new address. You may first need to use Request Password to have a new password assigned to your new address, if you haven't logged in with it before.
Return to the owner/moderator editing page, and remove your old address.

Creating groups

Click Create Group, and choose a Group Name, Type, Subject, Topic, and Description. Be sure to fill in all five areas of the form, and remember that the group name is also part of an email address, so it must contain no spaces (you can use dashes or dots or underscores if you need to separate words) and no strange characters (#, &, (, /, etc.). The type decides the most important settings, which you can later adjust. These include:

General Settings:
- Who can see the group's directory listing
- Owners
- Moderators
Message Handling:
- Who can send
Privileges:
- Who can view list's info page
- Who can subscribe
- Who can unsubscribe
- Who can review subscribers
Archives:
- Web archives access rights

Adding subscribers

You can add subscribers one at a time, or you can import a list of subscribers by clicking Import List and following the guidelines on the page. Choose the appropriate action (add or invite). Select the Quiet box if you do not want everyone to receive a Welcome message. Note that you don't have to worry about double-adding somebody who's already subscribed; they will not be added to the list a second time (and they will not receive another Welcome message if they're already subscribed).

People can also subscribe or unsubscribe themselves, using the Web-based or email-based subscribe and unsubscribe commands, if the group is set to allow those actions under Manage Group -> Change Settings -> Privileges. See the NPOGroups Subscribers Guide for details.

Posting messages

You can post to the group either by hitting the Post button, or by simply emailing the group address--groupname@npogroups.org (for Basic) or groupname@lists.your-domain.org (for Custom)--from your own email software. As long as you send from an address that has permission to post to the group, the message will be distributed to all subscribers. Who has permission to post is controlled by the Who can send setting, under Message Handling settings. Only Moderators (not Owners) can send to newsletters, although if there are no Moderators set explicitly, the Owners are privileged as Moderators too.

All subscribers can send to discussion groups, although if they want to reply to a list message and have their reply go to the whole group, they should use Reply to all in their email software. You can change that behavior, so that replies to list messages automatically go back to the whole group, by changing the Reply address setting under Message Handling to "list". However, we do not recommend configuring groups this way, for reasons of prudence and etiquette: it's generally much worse to have a reply (or an automated vacation message) unintentionally go to a whole group than it is to have something meant for the group accidentally go to one person, so the latter should be the default behavior.

You can use HTML formatting and it will be distributed as-is, and preserved in the archives. If you use Outlook, be sure the formatting is set to HTML and not to "Microsoft Rich text", which is a Microsoft-only format that will be stripped from list messages.

Accepting subscriptions from your Web site

You can add a form to your Web site to accept subscriptions, and the easiest way is to have it invoke the customized CGI script that we provide for this purpose. You need to do two things: First, notify us that you will be using this script and provide your Web site's domain name, so that we can allow your site to call this script. Then, simply insert this code snippet (or use it as a model) in your Web page:

<form action="http://electricembers.net/cgi-bin/npogroups.pl" method="post" 
 target="_blank">
Enter your name:<br>
<input type=text name="realname"><br>
Enter your email address:<br>
<input type=text name="email"><br>
<input type=hidden name=listname value="LISTNAME">
<input type=hidden name=hostname value="HOSTNAME">
<input type=hidden name=action value="subscribe">
<input type=submit value="Subscribe">
</form>

Substitute the list you want them to subscribe to for LISTNAME, and for HOSTNAME substitute either "npogroups.org" (if using Basic) or your custom list host name, eg. "lists.your-domain.org" (if using Custom). If you don't want to require the real name too, then just omit the lines that ask for it. Of course you can make other changes too, such as substituting a pull-down menu or radio buttons with multiple listnames to choose from, or changing the "subscribe" command to "unsubscribe", if you're comfortable editing forms. You can also set variables like a custom "thank you" page. This script is a modified version of the standard NMS FormMail script.

Message footers

Messages distributed to a group will automatically have a footer appended if the message is plaintext, or else attached if the message is HTML, giving brief instructions to subscribers on changing settings or removing themselves from the group. Footers cannot be appended in-line to HTML messages because of inherent uncertainties in adding text to an HTML-formatted document.

Managing bounces

The NPOGroups system automatically handles bounces, ie. mail delivery failures. Delivery can fail for a number of reasons, some temporary and some permanent, such as a problem with the recipient's domain name, a recipient's mailbox going over-quota, an invalid recipient address, or the recipient's mail server blocking our traffic due to over-zealous spam protection. Subscriber addresses that bounce are given a bounce score that climbs with successive failures based on a (somewhat obscure) formula, and permanently bouncing addresses are eventually cleaned automatically from the list.

Click Bounces to see the list of addresses that bounced, and the range of dates they have been bouncing. Clicking any bouncing address will give you options to update the address, unsubscribe it, or even view the last bounce, which shows you the actual mail delivery error and should reveal the reason for the bounce.

If you notice or receive an email message saying that the bounce rate (percentage of subscribers who are bouncing) is high on a given group, you can simply wait for their bounce scores to climb high enough that they are automatically deleted, but you may also want to quickly check that there isn't some unusual or fixable problem. If something in the bounce message is confusing or suspicious, we can help by explaining it or investigating any systemic problems that may have come up.

There is more information about bounce scores in the FAQ.

Deleting groups

Click Remove Group which will turn off the group's functioning while keeping its configuration and data intact. If you are sure you want the group removed completely, it should be purged. With NPOGroups Basic, we need to do that for you, so please contact us. With NPOGroups Custom, under the Domain Admin tab, click Closed Lists, select the group(s) you want to purge and click the Purge button.

Retrieving subscriber lists

You can download a text listing of a group's subscribers using the Export List button on the Subscribers page -- if you're looking at the Bouncing subscribers page or have filtered on a search term, then only those subscribers will be exported. You can also retrieve a full subscriber list via email, by sending a message to sympa@npogroups.org (or sympa@lists.your-domain.org for Custom), with the command "review groupname", using the name of the desired group for groupname. If you have permission to access it, you will receive a tab-separated text email message listing each subscriber's email address, full name, and subscription mode.

Customizing templates

The NPOGroups system allows you to customize the templates for various administrative messages (eg. the welcome message, invitation message, message footer), but caveat editor: These templates are filled with obscure code of several types that requires some care and may cause problems if edited improperly. You can always avoid any such problems by simply sending us the full text of any changes you would like to make and we will insert them for you, but if you have a technical bent and want to edit the templates yourself, there are really only a few things to learn.

There are three types of code that may be found in any template:

MIME part markings, separating plaintext from HTML portions of a template. These look something like:
```
  --===Sympa===
  Content-Type: text/plain; charset="UTF-8";
  Content-Transfer-Encoding: 8bit
```
You should never need to edit these, and can edit whatever you like around them, but note that these separators are an indication that the message's text appears twice in the template, once in plaintext and once with HTML markup. If you want to change the text, you have to edit it in both places, and if you want to insert links in the HTML portion, you have to surround them with proper <a href=""> </a> tags.
Localization (multilingual) markup, for automatic translation into different languages. This consists of a beginning and an end tag bracketing a piece of text, such as:
```
  [%|loc(list.name,list.host)%]Welcome to list %1@%2[%END%]
```
The [%|loc%] tag marks the beginning of a localization string, the [%END%] tag marks the end, and the %1 and %2 within the string are variables, which are filled by the list.name and list.host values enclosed within the [%|loc%] tag. This string is used as the key to a dictionary that translates into whatever language the user has set -- in other words, there's a file on the system that translates "Welcome to list %1@%2" into "Bienvenue sur la liste %1@%2" for those selecting the French language, "Bienvenido a la lista %1@%2" for those using Spanish, etc.
So the significant point here is, if you edit anything between those tags, the key will no longer match the dictionary and that piece of text will no longer be translated automatically. If you don't care about that, then there's no problem and you can go ahead and edit as you like. However, be careful not to mangle any [%|loc%] or [%end%] tags and only delete them in matched pairs (beginning and end), or there will be an imbalanced tag error that will result in broken functionality.
Template Toolkit 2 (TT2) markup, which covers anything else found within [%...%] markers. This can range from the simple insertion of variables (eg. "[% list.name %]") to standard programming syntax (conditionals and loops) as well as special functions, both shown here:
```
  [% IF user.password %]
  [%|loc(user.password)%]Your password is %1[%END%]
  [% END %]

  [% TRY %]
    [% INSERT "info" %]
  [% CATCH %]
  [% END %]
```
You generally should not edit any such code, but you can remove it as long as you delete all parts of a code block, to avoid leaving incomplete syntax that will lead to broken functionality. For instance, the second code block above, from [% TRY %] to [% END %], simply says to look for the file called "info" and insert its contents at that point if it's found, and do nothing if it's not. If you don't want the contents of the info file included there, you could edit out all four lines entirely.

Feel free to try editing templates based on this information, but also feel free to send us changes instead if you want us to edit them for you.

Including one group in another

If you have several different groups and sometimes need to send a given message to all of them, but don't want to maintain a separate master group or to have people subscribed to multiple groups receiving multiple copies, you may want to use the NPOGroups list inclusion feature. In a limited way, this feature compensates for NPOGroups' inability to "segment" a group, ie. send only to those subscribers that live in California, because you can maintain separate groups (say, for different states) and send either to the individual target groups or to the master group, as desired. Please note that this configuration changes or invalidates certain assumptions about getting on and off groups and may cause subscriber confusion, so read these instructions fully before embarking on it.

You're going to create a "master group" that includes the subscribers of several other groups, so start by creating a new group (or you can add this feature to an existing group with its own subscribers). Then, under Manage Group -> Change Settings, go to the Data Source page, and check that the User Data Source is set to "include2". Don't click Update yet.

In the List Inclusion field, enter the name of one of the groups whose subscribers you want included in the master group. Click Update. Repeat to add the names of any other groups you want included. Now check the Subscribers page and confirm that all the subscribers of the included groups have been brought into this one, and you're just about done. You can send to them all by posting to the master group.

Keep in mind that people may not know why they're now receiving messages on this new group, which they didn't sign up for, so you might want to include a note at first, or even in every message (which can be done with the Message Header template under Manage Group -> Edit Templates), to explain how it works.

The biggest issue will probably be that the standard methods for users to unsubscribe themselves will not work, if they're included from other groups. Ie. if they try to unsubscribe from the master group, it will simply tell them unsubscription is not allowed, because they can't do that directly; they can only unsubscribe from the original group(s) that they've been included from. There's currently no way to tell each person which group(s) they're originally subscribed to, other than having them log in to the Web site and look in the Your Groups box, or sending the "which" email command to sympa@npogroups.org or sympa@lists.your-domain.org.

So the unsubscription info in the default message footer of the master group will be incorrect, and you will need to modify it from Manage Group -> Edit Templates to account for this difference. It could give instructions to contact the group owners (the owner address for any group is groupname-request@npogroups.org or groupname-request@lists.your-domain.org) for help with unsubscription, or else instruct users to view and manage their group subscriptions by logging into the Web site.

Setting up NPOGroups Custom

Before we can set up NPOGroups Custom under your domain name, you will need to visit your DNS provider (usually your Web host) and create the hostname that you will use for the list server. Usually this will be lists.your-domain.org. Add the following NS (Name Server) records to your domain's DNS:

          lists    IN     NS     ns1.electricembers.net.
          lists    IN     NS     ns2.electricembers.net.
          lists    IN     NS     ns3.electricembers.net.         (optional)
          lists    IN     NS     ns4.electricembers.net.         (optional)

Some DNS providers don't allow this NS record type, despite it being the standard way to delegate DNS responsibility of a subdomain to different nameservers than the rest of the domain's DNS. If you have such a DNS provider, you can still get NPOGroups Custom service working as long as they let you create A (Address) and MX (Mail eXchanger) record types:

          lists    IN     A      209.209.81.70
          lists    IN     MX     10 smtp.electricembers.net.

We will send you a link with very detailed instructions when you sign up.

Windows 2000 Network Note
If you're on a Windows 2000 Server network, using DNS via Active Directory (ie. logging into a domain), and if your domain is named the same as your Internet domain, then you will also need to duplicate these records in your local DNS configuration. Otherwise, even though the new host is visible to everyone else in the world, it will not be visible from within your network. To do so, add a "New delegation" in your primary zone, with the name "lists", pointing to ns1.electricembers.net, ns2.electricembers.net and ns3.electricembers.net (hit Resolve to get it to pull down their IP addresses automatically).
If your Active Directory domain name is different than or a subdomain of your Internet domain (eg., "office.your-domain.org"), then you can ignore this.

We can do some basic customization of the site, namely: the site title, addition of a logo, general color scheme, the list of topics under which groups are categorized, and whether the initial homepage shows the directory or goes straight to the full listing of all groups. If you have requests for these items, please send the necessary information, which could include a properly sized logo image (100 pixels high or less), hex color codes or reference to an existing Web page with desired colors, etc.