User Documentation for Mailing List Manager

After installing mailing-lists, categories, users-selection, acs-mail-lite, mail-links and acs-datetime, you should first deal with categories so that you can later categorize mailing-lists in several dimensions (called category trees). According to the spec, greenpeace will categorize mailing lists in the dimensions region (i.e. united states, germany...), campaign (i.e. rainforest, whales, war...) and target (i.e. press, cyberactivists...), but other dimensions (trees) can be added.

To setup these categories, you use the admin interface of the categories package to add category trees - let's say 'regions'. Then you can add top-level nodes to this tree - like 'north america', 'europe'. After that, you can add child nodes to these categories - like 'germany' and 'france' in europe and 'united states' in north america. Since the category package is multilingual, you can select a different language from the select box and start translating the categories by editing them. Later, a user will see then see the categories in the default language that he set in his settings.

After you setup some category trees, you can use the context bar to go to 'Main Site' and then to the mailing list package. At the top of the admin interface, you can now use the link 'Administer Categories' to come back to the categories package to now mount some of your created category trees to the mailing list package so that they can be used to categorize lists. You can choose to use whole trees or only subtrees (you then have to select where the subtree should start), but you normally would use a whole tree.

After you mapped your trees to mailing lists, use the context bar to come back to the mailing list package. By using the link 'Change Visible Categories' you can select, which category trees should be seen by users when browsing to look for other interesting lists (for example, you may want to decide that the users can only look through the list of existing mailing lists by region and by campaign, not by target).

The categorization system is also used to store the information which user is coming from which country. To tell the system which category tree to use for this user categorization (the regions tree), you have to use the link 'Change Country Category'.

Since the mass subscribtion will be done by providing a list if emails and country codes, the system will have to know which country is meant by what country code. This mapping can be done by using the link 'Administer Country Codes'.

The mailing list manager can not only be used to spam mailing lists for which users have signed up, but also to spam a list of users selected by a custom sql query. These sql queries can be managed by the users selections package. In this package, an admin can write sql queries containing bind variables for which he provides default values. These queries can be administered and their results tested for different bind variable data by using the link 'Administer Users Selections'.

Mailing Lists

When adding a new mailing list, the user has to provide a name, select the language the list will be in, enter some teaser text to be displayed in the users list of available mailing lists and categorize the list in the category trees mapped to this mailing list package. In addition to that, the user has to provide data for the confirmation-, welcome- and reminder-emails sent out by the system: The emails need a sender email address, a subject, a body and a mime-type (either plaintext or html). Since the user being mass subscribed to a mailing list is not yet known to the system, it is not possible to use dynamic variables like @user_first_names@ that will be replaced by the users first name (you can do that in the mail jobs or mail classes later).

To include a link to confirm the subscribtion, you can use @link@ in the confirmation- and reminder-emails. To tell a newly added user his password in the confirmation- or welcome-email (we can't figure out the password when sending reminder emails since they are stored encrypted) you should use code like

<if @user_password@ not nil> Your new password is: @user_password@ </if>

Further data for mailing lists are the date when the mailinglist will expire (just set it to some date in the far future if no expiration date needed) and the number of days after a user received the first mail to confirm the subscribtion to a new mailing-list that a reminder email will be sent out. For example, if you set the 1st reminder to 7, then the user will be reminded after a week to confirm the subscribtion. If you want to remind only once, just enter 0 as 2nd reminder. After all that, you can enter some comment to that new mailing list to maybe explain some other admin what this is all about.

After the creation of a mailing list, you will see it at the index page together with the information how many users are subscribed to it or still need to confirm the subscribtion and you will see links to delete that mailing list and manage the permissions to it. You can edit the mailing list data by clicking on the lists name. When managing permissions, you can make a list public to all mailing list admins (so they can use and edit it), or you can grant some other specific other admins the rights to use and/or edit it. The list of other admins will contain only those admins that are not general mailing-list package-admins, because they can always see and edit all mailing lists or mail classes.

If you want to mass subscribe some users, you have to select to which list you want them to be subscribed and provide a comma seperated list (csv) of emails and contry codes (see administring country codes) and check if you want them to be asked for confirmation or if you just want them to be immediately subscribed. The users will then either receive a confirmation email or a welcome email. If an email is not known yet, a new user will be created.

Mail Classes

A mail class is a template for a new mail to a mailing list or a users selection. When creating a new mail class, you have to choose if you want the mail class to be a template for a plaintext email, a html email or a mixed email with both a plaintext and a html part. After that, you will see the form asking to provide a name, a language the mail will be in, a sender email address, a subject, header, body and footer for the mail. The header and footer can be used to set a fixed beginning and end for a mail framing a mail-specific body. Please note that there will be no additional newline or anything inserted between these three parts. The user can also define in a mail class if the subject, header, body and footer can later be changed when actually using the mail class in a mail job or if they will be fixed. Further, a css-file can be uploaded and attached to a mail class and comments can be given to other editing admins.

After creating a mail class, you can edit, delete or copy this class or manage the permissions for it - just as for mailing lists.

Mail Jobs

When creating a new mail job, you will be asked which mail class you want to use and which mailing list or which users selection you want to spam. Then you will see the mail job form where you can set the language of this mail job, change the sender email and edit the mail subject, header, body and footer - if the used mail class lets you do that. When spamming a mailing list you can use the variables @user_id@, @user_email@, @user_first_names@ and @user_last_name@ which will be dynamically replaced with the appropriate data for every user. When spamming a user-selection, you can change the used bind vars of the query if some exist and you can use all query columns of the query in the form @column_name@ in the mail text. In addition to that, you can upload and delete mail attachments (the css-file of the mail class will be shown if it has one). To upload a new attachment, you have to use the ok-button of the form and you will get to the same form again and again until you don't upload a new attachment. After uploading all atachments, you can decide if you want links used in the mail text to be tracked so that every click of users to these links will be recorded by the system.

If you use this feature, the system will look for links beginning with http:// in the plaintext part of the mail and for links like href="http:// in the html part. In the end, you can set the execution date (default: mail will be send in the next 20 minutes) and set the mail job's status as active or suspended. Please note that when uploading attachments, the status will be automatically set to suspended and you therefore need to set it to active again when finally submitting the mail job. Before the mail job gets created, you will see a confirmation page showing you the final email.

You can see pending mail jobs by using the link 'Pending Mail Jobs'. Here you can edit the mail jobs, delete, suspend and activate them. Processed mail jobs can be found by using the 'Mail Job History'. By using the 'Mail Links' link for mail jobs found, you can then see how many users clicked which link in the mail.