Groups Administrators – Electric Embers

The following information is for administrators (domain admins, list owners, moderators) of our Groups service. If you are looking for subscriber-level information, see the Groups Subscribers Guide.

Roles and privileges

There are four different types of privileged users (the first two controlled from Manage Group -> Users, then Owners or Moderators):

All Groups

List Owners: 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. Default is the group’s creator.
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: Requesters are able to set up new groups (which go live only with approval from a Domain Admin.) Electric Embers can change who has Requester privileges for you.

Custom Groups only

Domain Admins: Domain Admins in a Custom domain have full access to all groups in their domain, and can create and close/purge groups as well. They also approve or reject requests for new groups submitted by Requesters. Electric Embers can change who has Domain Admin privileges for you.

In order to create or manage groups, you must log in to the Groups system with an appropriately privileged address. If you have Groups Basic, you log in at https://groups.electricembers.net (or https://npogroups.org for legacy accounts), while Groups Custom will be under your own domain, usually like https://lists.your-domain.org, If you don’t know your password, or lose track of it at any point, click Forgot Password at upper left. You can then change your password from the Preferences page. You can also change your subscribed address under Preferences, which updates your subscriber, moderator, and owner address for all groups.

Creating groups

Click Create List, and choose a List Name, Type, Subject, Audience, 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

Test groups

If you’d like to create a group for testing (to play around with settings, learn more about how Groups works, or test/troubleshoot messages before you send them out to your real subscribers) you can and should! It won’t cost you anything extra as you can create as many groups as you like.

Adding subscribers

From the Subscribers page, you can add subscribers one at a time, or you can import a list of subscribers by clicking Multiple Add and following the guidelines shown there. Select the quiet box if you do not want everyone to receive a Welcome message, then click the appropriate button (Add subscribers or Invite). 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 Groups 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@domain with the group’s name substituted for “groupname” and its domain (npogroups.org, groups.electricembers.net, or a custom lists.your-domain.org) substituted for “domain”, from your regular 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.

Managing bounces

The Groups system automatically handles bounces (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 accumulate points toward a bounce score that climbs with successive failures, 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.

Subscribers appear in the Bouncing Subscribers table when a list message to them is rejected by their mail server. But the Bounce Score displayed in the table is not just the number of bounces; it’s calculated from a formula that depends on the number of bounces, the severity of the bounces, and the frequency of bounces compared to the frequency of traffic on the list. Also, bounces are purged from the system when they’re 30 days old, so that data is only accumulated over the last 30 days. If a subscriber has a temporary (low-severity) bounce once every month or two on a list that gets a lot of traffic, their bounce score may show up as zero.

If the most recent bounce date shown for a subscriber in the table is older than the most recent traffic on the list, then it must have been a temporary bounce and they must have successfully received later messages. To see more detail of why someone bounced, click their address in the list and look at the Status line, which will say something like:

    Delivery not authorized, message refused (5.7.1)

This is the actual rejection message from their mail server, and it should give some idea (however cryptic) of why the message was bounced. To try to see more detail, you can click the View Last Bounce link below that line, which will show the rejected message in its entirety. Usually you can ignore the Bouncing Subscribers table, and people will either have their status reset after 30 days or be removed automatically from the list if their bounce scores climb high enough. If you see that there are a lot of temporary bouncers on there and you want to clear them out, you can select them all and hit the Reset Errors button to give them a clean slate. Or if they’ve been bouncing for a long time and their bounce scores are remaining low because of the type of bounces and the list’s traffic pattern, they’ll never reach the threshhold to be automatically unsubscribed, so you can select them all and hit the Delete Selected Email Addresses button to unsubscribe them from your list.

Retrieving subscriber lists

You can download a text listing of a group’s subscribers using the Export Subscribers 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. Note that there is no way to download a list of the people who have unsubscribed, as these addresses are simply removed from a list and no longer stored anywhere. If you need to track unsubscribers, you can use the “notify owners” option on the Who can unsubscribe setting in the group’s permissions in order to receive emails each time someone unsubscribes, and then process and store that data in your own system.

Exporting archives

To export and download a group’s message archive, navigate to Manage Group -> Manage Archives, select the months you want to export, and click Download .zip archive. The archive export produces a zip file, which when uncompressed contains a folder for each month of archived messages. Inside those folders are individual files, one per archived message. Each file is a plain text file containing exactly the raw headers and content of a message as distributed by your group.

As plain text files, they can be read with any simple text editing program (or web browser or word processor), but they’re not particularly legible that way because of the technical header information and because of the way HTML mail and attachments are encoded. To view the messages in a more natural and legible way, you can import them into an email program (like Mozilla Thunderbird, Mac Mail, Microsoft Outlook). Different programs will work differently, but most will be able to read these files as email messages and work with and display them accordingly.

Deleting groups

Under Manage Group click Close 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. If you’re using Groups Basic, we need to do that for you, so please contact us. If you use Groups Custom, your domain admin can purge your closed groups: under the Domain Admin tab, click Closed Lists, select the group(s) you want to purge and click the Purge selected lists button.

Using email commands

Many Groups functions are available as email commands as well as through the web interface, although the web interface is easier and more versatile in almost all cases. If you are doing something that requires an email-based interface to list management, see the Sympa Email Command Guide.

Discussion list etiquette and terms of use

Discussion lists can make for wonderful community. But sometimes when they grow large enough, age long enough, or meet up with controversial issues, email discussion lists can get out of hand. What once was a natural extension of friendly or professional communication can surprisingly quickly become an uncomfortable place, marked by anger and disrespectful personal attacks. It is each list owner’s responsibility to manage their list on behalf of their organization or their community.

To deal with difficult situations (and hopefully head them off in advance) in a fair and transparent manner, many list owners have found it helpful to create and enforce clear community guidelines.Terms of use are rules for participating in a discussion list (DON’Ts) and a clear explanation of what will happen if the rules are broken. List etiquette is a collection of suggested best practices (DOs) which can keep a mailing list useful and comfortable. We encourage each list owner to create and publish their own etiquette and terms of use, drawing on the many examples which quick web searches can uncover.

Accepting subscriptions via your Web site

The easiest way would be to publish the -subscribe address of your group. Say your list was example@lists.domain.org, then the subscribe address would be

example-subscribe@lists.domain.org.

Alternatively you could link to your group’s homepage, or the URL of the subscribe link in the left bar of your group.

DNS for Custom Groups

Before we can set up Custom Groups under your domain name, you will need to add some records to your domain. To do that, visit your DNS provider (usually your Web host, but we can help you figure out who it is if you’re unsure) and create the hostname that you will use for the list server.

=== Preferred Method ===
If you can create the following 2-4 records, you don’t need any of the others listed below. Add the following NS (Name Server) records to your domain’s DNS, which will delegate lists.your-domain.org to our nameservers, making us authoritative for the subdomain:

Minimum required:
  Type: NS  |  Name:  lists  |  Value: ns1.electricembers.net
  Type: NS  |  Name:  lists  |  Value: ns2.electricembers.net
Optional:
  Type: NS  |  Name:  lists  |  Value: ns3.electricembers.net  
  Type: NS  |  Name:  lists  |  Value: ns4.electricembers.net

Caution: If your DNS control panel doesn’t give you a place to specify the record name (“lists”) on the NS records, DO NOT edit NS records at all. This is likely to break all existing services in your domain! See the Alternate Method described next.

=== Alternate Method ===
Some DNS providers don’t allow this NS record type, despite it being the standard way to delegate DNS responsibility for a subdomain to a different provider. If you can’t create custom NS records, you can still get Custom Groups service working as long as you can create A, MX, and TXT records with custom host/record names, as follows:

Type: A   |  Name: lists  |  Value: 208.90.215.70
Type: MX  |  Name: lists  |  Precedence: 10  |  Value: smtp.electricembers.net

Caution: If your DNS control panel doesn’t give you a place to specify the record name (“lists”) on the MX record, DO NOT edit MX records at all. This is likely to break normal incoming email service for your domain! Please consult us in this case.

Finally, to avoid having your list messages spam-filtered, you should also create this TXT record to enable DKIM authentication:

Type: TXT  |  Name: npogroups._domainkey.lists  |  Value: k=rsa; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCgmyvwYDwrhkxkbidHwrJfGj24I76THWMGt+Z7jTN7vaH4IeeJw6hvp2Sp3q5/6YbGvlkbzutrMfhOxU6lD5CLyv2BgOr6C6WQCLKjWCPCieNF4OPs2lrc8jd+zChPxNQSVd5zWOTyTWXQDH8d9D1MoyoO2Kn4oV+MO3FmTv9oTwIDAQAB

and this one to set a DMARC policy:

Type: TXT  |  Name: _dmarc.lists  |  Value: v=DMARC1;p=none

and add this record for SPF authentication:

Type: TXT  |  Name: lists  |  Value: v=spf1 include:groups.electricembers.net ~all

Customizing your Custom Groups website

For Custom Groups domains, we can do some basic customization, namely: the site title, addition of a logo, 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. You can also edit the colors used in the web interface yourself, following these steps:

Login as a domain administrator, and from the top menu bar choose Domain Admin
From the navigation menu, choose Skins, CSS, and colors
Find the color controlling any given page element, click its color selector, and choose a new color
Click Test this color in my session
If happy with the choice, click Install my session colors in a new static CSS
Or to restore the previous settings, you can always click Reset colors in my session

Customizing templates

The Groups 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.

For the technically adventurous, the variables available in templates and within list messages are documented here.

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 manage a separate group for all recipients or to have people subscribed to multiple groups receiving multiple copies, you may want to use the Groups list inclusion feature. In a limited way, this feature compensates for Groups’ 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 parent group, as desired.

You’re going to create a parent 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, in that new group under Manage Group -> Change Settings, go to the Data Sources page.

In the List Inclusion field, enter the name of one of the groups whose subscribers you want included in the parent 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 parent 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 (perhaps by editing the Message Footer template under Manage Group -> Edit Templates), to explain how it works.

Using the SOAP interface

The Groups Sympa software includes a SOAP server interface, to facilitate integration with your Groups service from other applications running on any Web server. The full description is in the Sympa docs, and the SOAP URL and WSDL are at https://domain/sympasoap and https://domain/lists/wsdl, with the group’s domain (npogroups.org, groups.electricembers.net, or a custom lists.domain.org) substituted for “domain”. If you have trouble using the login command, specifically that it seems to work but the server continues telling you to login before you can run commands, we recommend using the authenticateAndRun method instead.