DLIST mailing lists

DList - Mailing Lists

DList - Quick Overview
What is a Mailing List?
Creating a Mailing List
Mailing lists on Virtual Domains
Adding Users to a List
Settings - lists.dat
An example lists.dat file
Welcome Messages
List Footers
Moderated Lists
Archives and Files
DList Email Commands
User's Real Names
Template Footers
Template Variables

Langauge translation Features

DList - Quick Overview

DList is a mailing list server that is automatically installed as part of SurgeMail
General settings for DList are contained in the main configuration file, dlist.ini.
To create a list you simply add a line like
list listname
setting in the filelists.dat which you will find in the DList directory. Then make SurgeMail reload the configuration file (DList regularly checks the configuration and lists.dat files for changes so it does not need to be sent a reload command).
Generally the sysadmin would set up a list and then users would send an email to the 'listname-request' address to 'subscribe' themselves to the list.
Users in general will only interact with the list by sending emails, either directly to the list to be 'posted' or to the listname-request address if they wish to join the list or send it commands. See:
DList mail commands
When users join the list they are normally sent this list of commands so that they know what the list can do for them.
To modify DList settings you can directly edit dlist.ini and lists.dat with a text editor or use the web admin tool.

Creating a Mailing List - Manually

To create a mailing list on the list server DList, you need to add a new list setting in the lists.dat file, eg:
list listname
where listname is the name of the list. You can edit the lists.dat file with a text editor (e.g. notepad or vi) or use the web admin tool.
If you are doing it manually then below the list setting add any other settings that you require for your list, eg:
title juggling
Issue a 'tellmail reload' command so that SurgeMail notices the new list
To try out the list, you should add a user to the list and then post a message to the list. For information on this see,
Adding Users to a List
DList Email Commands
Creating a Mailing List - Web Interface.

You can also create mailing lists in the web admin, domain admin or user self admin interfaces. You can define defaults for new mailing lists by creating a file called list_defaults.txt in the web directory, in that file place the defaults you wish, e.g. to see what variables exist examine na_list.htm, in general prepend 'list_' to the dlist setting. e.g.
 	list_archive true
	list_reply_to_user true
NB: Mailing lists on Virtual Domains...
If you are wanting to add the mailing list to a specific domain eg: a virtual domain, then you need to specify that domain in lists.dat so that SurgeMail can create the correct aliases for your mailing list.
There are two ways to do this.
1. Old way: add a domain setting to your list eg:
list juggling title Mailing List domain vdomain1.com
2. New way: create the list with a full list name, eg:
list juggling@vdomain1.com title Mailing List
The second method is better because it means that all mailing list directoryies will be created with unique names. This allows you to reuse mailing list names on different domains.

Settings - lists.dat

Lists.dat is the file where you create all the lists on your DList server and where you enter individual settings for each list.
All settings are one per line, and you can exclude a line by starting it with the '#' character. You do not need to reload the DList server after making changes.
Below is a list of all of the settings available for each list. All settings for a list are entered on the lines following the
list listname
line that declares a list, before the next list starts with its 'list listname' declaration line. See example lists.dat file
All settings take just ONE value except where stated otherwise in the description.
Note: In the table below you will see that the 'access' settings can generally take one of the following values. It is important to think about what these settings mean - NOT all of them apply to every access setting!

member - refers to list members and in general the list moderator as well
anyone - no restriction
moderator - only the list moderator can do it
*domain - person trying to do it must have the email address ending in 'domain'

Setting Default Example/options Description

allow_ip * 10.1.2.* List specific IP addresses that can send to this mailing list, good for securing a large outgoing only list against spam

access_join anyone anyone,*netwinsite.com, Controls who can join the mailing list

access_leave anyone moderator Controls who can unsubscribe from the mailing list, by default anyone can unsubscribe anyone else.
in version 2.5d (2.4k) and above:
members: (can unsubscribe themselves, moderator can unsubscribe anyone)
moderator: (only moderator can unsubscribe - members cannot unsub themselves)

access_post members moderator Controls who can post messages to the mailing list

access_get members moderator Controls who can get messages or files from the archive.

access_who moderator members Controls who can retrieve the list of current members. Note the default changed from members to moderator in SurgeMail 2.3

archive false true If set DList will record all incoming messages in an 'archive' sub directory, off the list's directory.

bounce_remove
(added in 2.8h) false true If set then DList will log all bounces that it receives, and if it can work out that the bounce was because of a permanent error, then it will remove that address from the mailing list. DList will also send a summary email to the moderator each day recording any addresses it has removed from the list and the bounce error that was the reason for the removal. This is a new 'beta' setting so let us know how it goes if you try it. You might like to try, the log_bounce setting as a first step to turning on this setting.

domain (none> domain mydomain.com Specifies the domain that this list should exist on where you do not want it to be on your first host_domain. NB: To allow listname re-use on different domains see the note,
Mailing lists on Virtual Domains

footer
(version 2.4h and above) (none) footer
c:\surgemail\dlist \listname\footer.txt The full path to a file that you want added onto the end of all messages as a footer. In version 2.8e and above this is only added onto all TEXT messages, HTML version also added see below. Note that as of 2.9g, template variables can be used in footers. See Template Footers for details.

footer_html
(version 2.8e and above) (none) footer_html
c:\surgemail\dlist \listname\footer_html.txt The full path to a file that you want added onto the end of all HTML messages as a footer. Note that as of 2.9g, template variables can be used in footers. Template Footers for details. PLEASE NOTE: this footer is NOT added to a message sent in 'text' only format, you must specify a text footer if you want a footer added to a text message (and a text footer can't contain html of course).

join_cookie_subject false true If set then the cookie code is in the 'subject' of the message, this makes it easier for users to join a list. Join_cookie should also be set to true.

join_cookie false true If set, when users join the list they will be asked to respond with a specific cookie (number) to prove they are real humans, this setting prevents people from subscribing other people or worse other lists to an existing list. Note: a cookie will not be sent if the subscriber is a moderator or if access_join for the list is set to moderator or password.

language_file
(version 2.9d and above) (none) newproducts.dat Used to specify a language file for a particular list. That language file is used to translate most of the phrases generated by DList for that list. Documentation on language translation is available here.

log_bounce
(version 2.8h and above) false true This is a debugging setting, that may be more generally useful. It causes DList to log all addresses that bounce and the reason for the bounce to the file, bounces.log, in the list home directory. The log is appended to for every bounce received when sending any messages to the list. See also, bounce_remove.

list (none) dnews-discussion The name of the list, this cannot contain spaces and must be the first setting for each new list in lists.dat

max_size 150 500 Limits the maximum size of an item that can go through the mailing list in kbytes. NB: this setting applies to messages to the -request address as well as the posting address.

max_per_user
(2.4g and above) 200
(changed from 50 in vers. 2.5d) 1000 Sets the max number of messages allowed to be posted to all lists on the server per user per hour. Note that the count is per user for posts to ALL lists, whereas the setting is per list. So the count is global but whether it applies to a list is list specific (the default is 200).

moderator (none) fred@netwinsite.com A list of one or more moderator email addresses, a moderator often has extra access rights, like the ability to subscribe other people etc. Separate multiple entries with spaces or tabs (or commas in version 2.5d and above), emails are only sent to the first moderator in the list, but any moderator can send moderated messages.

no_processed_message
(version 2.9d and above) false true This setting is very powerful. If set to 'true' for a particular list, no command processed messages are sent by DList for that list. This means that users will only see list posts; they will get no response to any DList commands they send (i.e. who, lists etc.). This would only really be useful if you wanted to subscribe users to a list without them receiving notices.

no_welcome_message
(version 2.9d and above) false true By default, DList sends a welcome message to each user directly after that user successfully subscribes to a list. If set to 'true' for a particular list, then users subscribing to that list will not be sent a welcome message.

reply_to_user false true (also in version 2.5f and above, user@domain) If set, the reply-to header in each message will be pointed to the original poster, rather than the mailing list, this is recommended for large mailing lists. In versions 2.5f and above in place of true you can specify an address as the reply address for ALL messages posted to the list. If given, posted messages will have any Reply-To: header turned into X-Reply-To:, and the address given is added to a new Reply-To: header.

status_interval 7 1 Period in days between automatic status reports being sent to the moderator.

skip_mailer_check false TRUE If TRUE then DList will not ignore messages from users called, MAILER-DAEMON (all in capitals). These are normally bouced messages and so would not normally be wanted as posts to the list.

skip_postmaster_check FALSE TRUE If TRUE then DList will not ignore messages from users called, POSTMASTER (all in capitals). These are normally bouced messages and so would not normally be wanted as posts to the list.

subject_prefix (none) Juggle: This string will be added to the front of every subject line of messages from this list, this makes it easy for people to sort list messages out from other messages.

title (none) N.Z. Juggling A title for the list, shown in headers and lists output.

invisible false true Makes the list invisible to the 'lists' command for finding lists on your server.

mod_web false true Add web links to accept/drop messages. Messages are stored so that the actual message with correct headers will go onto the list

mod_first false true If user has never posted before send their post to the moderator for approval, on subsequent posts the user can post direct. (Useful to stop spam abuse of lists)

notify_joinleave false true Send the list owner/moderator an email when users join/leave the list

auth_post false true STRONGLY recommended for private lists and large mailing lists. Only allow posts from local authenticated users.

auth_who false true STRONGLY recommended for ALL lists. Only allow who requests from local authenticated users.

auth_moderator false true STRONGLY recommended for all lists where the moderator is a local user. Requires that the moderator uses smtp authentication to prove they are genuine.

to_user false true If true then the To: address in each message sent will be the users email address instead of the list name

An example lists.dat file with entries for two lists, talk and juggling:

list talk

archive true

title The list for talkers.

subject_prefix [list: talk]

access_join Anyone

access_post Moderator

access_who Anyone

access_get Anyone

moderator talk.master@macro.com

max_size 40

footr c:\surgemail\dlist\talk\footer.txt

list juggle

title The list for jugglers.

subject_prefix [Juggle]

access_join Anyone

access_post Anyone

access_who Anyone

access_get Anyone

moderator juggling.master@macro.com
max_size 40

footer c:\surgemail\dlist\juggle\footer.txt< /td>

Welcome Messages

DList comes with an example welcome message. It is stored in a file called join.tpl in a template format.

You can edit this template to the look that you require, and you can copy it to each list's directory (off the main DList directory) so that individual lists can have their own welcome message.

DList supports variables in templates as of 2.9g. All you need to do to use template variables is add the variables you want into the template. or information on how to use template variables, and a list of supported variable names, see Template Variables.

The template files current supported are:

join.tpl

leave.tpl

These files can be in the main dlist directory, or in a specific dlist sub directory.

Adding users to a list

Usually users would add themselves to a list by sending a message to the list request address eg: listname-request@domain with the word subscribe in the message body.
DList will then add them to the users.lst file for that list. Users.lst for each list is stored in that lists directory (named after the list) off the DList directory (probably \surgemail\dlist\listname\users.lst or /usr/local/surgemail/dlist/listname/users.lst )
To add a number of users you have two options:

Add yourself as a moderator for the list and send the listname-request address a message with mutliple subscribe lines in the body.
So as a moderator you send the following email:
To: listname-request@domain From: your_moderator_address subscribe bob@domain1.com subscribe judy@domain1.com subscribe george@domain99.com
to join up the email addresses,
bob@domain1.com
judy@domain1.com
george@domain99.com

Directly edit the users.lst text file for the list and add the email addresses one per line.
So to add the same three users, you might edit the users.lst file to look like this:
u:tam@1.2.3.4 f:Tam Willacy p:0 t:0 bob@domain1.com judy@domain1.com george@domain99.com
where the first line is an existing user on the list.
Don't worry about the format of lines for existing users. The next time DList has to write anything to the users.lst file it will add the email addresses that you have pasted/typed in correctly.

Adding Users' Real Names
To specifiy the users real name when you are subscribing them using either method, enter the users email address with the full name field as per an email client eg:
sending subscribe commands:
subscribe "bobby" bob@domain1.com subscribe "Judy Simpson" judy@domain1.com subscribe george@domain99.com "Georgie Porgy"
directly in users.lst:
u:tam@1.2.3.4 f:Tam Willacy p:0 t:0 "bobby" bob@domain1.com "Judy Simpson" judy@domain1.com george@domain99.com "Georgie Porgy"
When the user subscribes themselves, the real name is taken from their email address (from the From header).

Moderated lists

There are several ways of posting into a moderated list depending on your settings:
access_post moderator

The simplist setting is: access_post moderator this is totally insecure. When a post comes in for the list the message is forwarded to the moderator, who then must post it again to the list. The 'from' address of the poster must match the moderator for the post to be accepted. Forging messages is so easy almost anyone can do this and post to your list directly!

access_post password

This setting relies on a password being set and then sent with every posted message, the password is stripped off the postd message, but this is very likely to fail with HTML messages so is also an unwise choice.

access_post moderator

auth_post true (or) auth_moderator true

This is the best setting, but it requires that moderated posts come from local users who are using smtp authentication, and also match the 'moderator' setting for the list.

Lastly for best security you can add "ALLOW_IP_MOD x.x.x.x" and list the ip address of the machine used to send the moderated messages.

Archives and Files

This is still being written :-)
DList lists can be set to save an archive of all messages by setting the list specific setting in lists.dat,
archive true
If this is set then DList will create the archive messages in a subdirectory called 'archive' below the lists directory eg:
c:\surgemail\dlist\listname\archive\1.msg c:\surgemail\dlist\listname\archive\2.msg
etc.
Then if the user sends an email to the listname-request address with the command, dir, in the message body DList will send back a message telling the user how many archived messages there are.
If the user wants one of the messages then they can send the 'get' command to fetch the archived message.
If you want to provide other files to the list members, then you create your own directory off the list's directory called, files, and put the files that you want to provide there eg:
c:\surgemail\dlist\listname\files\picture.jpg
Then when the user does a 'dir' command they will also be shown a list of other files available.
For details on the list commands see, DList Email Commands

Template Footers

DList will treat footer files as templates. This means that you can use variable names in the footer file. These names will be replaced with the actual values as the message is sent. For information on how to use template variables and a list of supported variable names see Template Variables.

Template Variables

Template variables are a way to customise joining messages and footers with information about a list or a list member. Variables are denoted in the following form:
	%%variable_name%%
When DList comes across a variable in a template (say a footer or a join message) it replaces that variable with its value. For example, the following line contains two variables:
	Welcome to the %%list_name%% list, %%h_user%%. 
The variables are replaced with their actual values when the message is sent. As an example, the above line could become:
	Welcome to the newproducts list, joe@bloggs.com. 
Below is a list of all template variables supported by DList. Please note that some variables may have multiple variable names. This is to ensure backwards compatibility with older versions of DList.

Variable Name Synonym Replaced With Example Value

list_member h_user The email address of the user to whom the message is sent. joe@bloggs.com

list_request_address
list-request The email address to which to send requests. newproducts-request@bloggs.com

list_address The email address to which to send list messages. newproducts@bloggs.com

h_fullname The users name, e.g. Joe Smith (if known in users.lst) You need to set body_template true to use template variables in messages you send John Smith

list_name_only The list name without the domain name newproducts

list_title The 'title' of the list New Products

list_name list
list-name The name of the list. Which is generally identical to the list_address (this variable exists for historical reasons, you probably want list_name_only instead) newproducts@bloggs.com

Some obscure/internal information

Digests

DList supports daily digests which are a compendium of all messages sent to the list within the past 24 hours.

The format of the users.lst file is very important. It is automatically generated, but for bulk additions you may need to modify it manually. If so, the format must be exact. Note: tabs are required - spaces will not be read as separating characters since they can be part of a full name. Also note this format is subject to change, the information here is provided as a guide, and it's fairly likely to remain accurate, but be warned :-)
     u:(data)<tab>f:(data)<tab>p:(data)<tab>t:(data)
     u: is the email address of the subscriber

     f: is the full name of the subscriber
     p: is an automatically generated and used for password verification subscriptions

	  t: is the type of subscription it is a bitmask.
     1 is digest delivery
     2 is disabled (no delivery)
     4 is holiday (no delivery but user can re-enable)

Examples:
     u:chris@xnetwin.xco.nz f:Chris P p:5112 t:1
     u:robert@xtellurian.xcom f:Robert Boyle p: t:0
Chris P is a digest subscriber he will receive one compiled post at midnight at chris@xnetwin.xco.nz.

Robert Boyle is an immediate subscriber he will receive posts immediately as they are sent to the list at robert@xtellurian.xcom

Note:
-----
When creating automatic scripts to subscribe an email address, the body of digest subscriptions messages to the listname-request address must be formatted as follows:

subscribe
digest true

This will subscribe the user and then set the digest mode for that subscription.

digest_textonly true - This option will strip all non-text MIME parts and only use the text parts to make the digest.

list_textonly true - This option will strip all non-text MIME parts and forward only the remaining text message to the list.

text_digest true - This makes the digest format simple non mime which many mail clients cope with better

The following alias addresses exist these allow you to join, leave and join for 'digests' by simply sending email to an address, with no 'body' content.

listname-join@domain.name = Join the mailing list.

listname-digest@domain.name = Join the mailing list, and set to receive 'digests'

listname-leave@domain.name = Leave the mailing list.

Setting	Default	Example/options	Description
allow_ip	*	10.1.2.*	List specific IP addresses that can send to this mailing list, good for securing a large outgoing only list against spam
access_join	anyone	anyone,*netwinsite.com,	Controls who can join the mailing list
access_leave	anyone	moderator	Controls who can unsubscribe from the mailing list, by default anyone can unsubscribe anyone else. in version 2.5d (2.4k) and above: members: (can unsubscribe themselves, moderator can unsubscribe anyone) moderator: (only moderator can unsubscribe - members cannot unsub themselves)
access_post	members	moderator	Controls who can post messages to the mailing list
access_get	members	moderator	Controls who can get messages or files from the archive.
access_who	moderator	members	Controls who can retrieve the list of current members. Note the default changed from members to moderator in SurgeMail 2.3
archive	false	true	If set DList will record all incoming messages in an 'archive' sub directory, off the list's directory.
bounce_remove (added in 2.8h)	false	true	If set then DList will log all bounces that it receives, and if it can work out that the bounce was because of a permanent error, then it will remove that address from the mailing list. DList will also send a summary email to the moderator each day recording any addresses it has removed from the list and the bounce error that was the reason for the removal. This is a new 'beta' setting so let us know how it goes if you try it. You might like to try, the log_bounce setting as a first step to turning on this setting.
domain	(none>	domain mydomain.com	Specifies the domain that this list should exist on where you do not want it to be on your first host_domain. NB: To allow listname re-use on different domains see the note, Mailing lists on Virtual Domains
footer (version 2.4h and above)	(none)	footer c:\surgemail\dlist \listname\footer.txt	The full path to a file that you want added onto the end of all messages as a footer. In version 2.8e and above this is only added onto all TEXT messages, HTML version also added see below. Note that as of 2.9g, template variables can be used in footers. See Template Footers for details.
footer_html (version 2.8e and above)	(none)	footer_html c:\surgemail\dlist \listname\footer_html.txt	The full path to a file that you want added onto the end of all HTML messages as a footer. Note that as of 2.9g, template variables can be used in footers. Template Footers for details. PLEASE NOTE: this footer is NOT added to a message sent in 'text' only format, you must specify a text footer if you want a footer added to a text message (and a text footer can't contain html of course).
join_cookie_subject	false	true	If set then the cookie code is in the 'subject' of the message, this makes it easier for users to join a list. Join_cookie should also be set to true.
join_cookie	false	true	If set, when users join the list they will be asked to respond with a specific cookie (number) to prove they are real humans, this setting prevents people from subscribing other people or worse other lists to an existing list. Note: a cookie will not be sent if the subscriber is a moderator or if access_join for the list is set to moderator or password.
language_file (version 2.9d and above)	(none)	newproducts.dat	Used to specify a language file for a particular list. That language file is used to translate most of the phrases generated by DList for that list. Documentation on language translation is available here.
log_bounce (version 2.8h and above)	false	true	This is a debugging setting, that may be more generally useful. It causes DList to log all addresses that bounce and the reason for the bounce to the file, bounces.log, in the list home directory. The log is appended to for every bounce received when sending any messages to the list. See also, bounce_remove.
list	(none)	dnews-discussion	The name of the list, this cannot contain spaces and must be the first setting for each new list in lists.dat
max_size	150	500	Limits the maximum size of an item that can go through the mailing list in kbytes. NB: this setting applies to messages to the -request address as well as the posting address.
max_per_user (2.4g and above)	200 (changed from 50 in vers. 2.5d)	1000	Sets the max number of messages allowed to be posted to all lists on the server per user per hour. Note that the count is per user for posts to ALL lists, whereas the setting is per list. So the count is global but whether it applies to a list is list specific (the default is 200).
moderator	(none)	fred@netwinsite.com	A list of one or more moderator email addresses, a moderator often has extra access rights, like the ability to subscribe other people etc. Separate multiple entries with spaces or tabs (or commas in version 2.5d and above), emails are only sent to the first moderator in the list, but any moderator can send moderated messages.
no_processed_message (version 2.9d and above)	false	true	This setting is very powerful. If set to 'true' for a particular list, no command processed messages are sent by DList for that list. This means that users will only see list posts; they will get no response to any DList commands they send (i.e. who, lists etc.). This would only really be useful if you wanted to subscribe users to a list without them receiving notices.
no_welcome_message (version 2.9d and above)	false	true	By default, DList sends a welcome message to each user directly after that user successfully subscribes to a list. If set to 'true' for a particular list, then users subscribing to that list will not be sent a welcome message.
reply_to_user	false	true (also in version 2.5f and above, user@domain)	If set, the reply-to header in each message will be pointed to the original poster, rather than the mailing list, this is recommended for large mailing lists. In versions 2.5f and above in place of true you can specify an address as the reply address for ALL messages posted to the list. If given, posted messages will have any Reply-To: header turned into X-Reply-To:, and the address given is added to a new Reply-To: header.
status_interval	7	1	Period in days between automatic status reports being sent to the moderator.
skip_mailer_check	false	TRUE	If TRUE then DList will not ignore messages from users called, MAILER-DAEMON (all in capitals). These are normally bouced messages and so would not normally be wanted as posts to the list.
skip_postmaster_check	FALSE	TRUE	If TRUE then DList will not ignore messages from users called, POSTMASTER (all in capitals). These are normally bouced messages and so would not normally be wanted as posts to the list.
subject_prefix	(none)	Juggle:	This string will be added to the front of every subject line of messages from this list, this makes it easy for people to sort list messages out from other messages.
title	(none)	N.Z. Juggling	A title for the list, shown in headers and lists output.
invisible	false	true	Makes the list invisible to the 'lists' command for finding lists on your server.
mod_web	false	true	Add web links to accept/drop messages. Messages are stored so that the actual message with correct headers will go onto the list
mod_first	false	true	If user has never posted before send their post to the moderator for approval, on subsequent posts the user can post direct. (Useful to stop spam abuse of lists)
notify_joinleave	false	true	Send the list owner/moderator an email when users join/leave the list
auth_post	false	true	STRONGLY recommended for private lists and large mailing lists. Only allow posts from local authenticated users.
auth_who	false	true	STRONGLY recommended for ALL lists. Only allow who requests from local authenticated users.
auth_moderator	false	true	STRONGLY recommended for all lists where the moderator is a local user. Requires that the moderator uses smtp authentication to prove they are genuine.
to_user	false	true	If true then the To: address in each message sent will be the users email address instead of the list name

Variable Name	Synonym	Replaced With	Example Value
list_member	h_user	The email address of the user to whom the message is sent.	joe@bloggs.com
list_request_address	list-request	The email address to which to send requests.	newproducts-request@bloggs.com
list_address		The email address to which to send list messages.	newproducts@bloggs.com
h_fullname		The users name, e.g. Joe Smith (if known in users.lst) You need to set body_template true to use template variables in messages you send	John Smith
list_name_only		The list name without the domain name	newproducts
list_title		The 'title' of the list	New Products
list_name	list list-name	The name of the list. Which is generally identical to the list_address (this variable exists for historical reasons, you probably want list_name_only instead)	newproducts@bloggs.com