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 to ensure delivery with DKIM/Dmarc/ SPF
The following rules should be observed now that DKIM/Dmarc is common, this is most important if the messages are from other domains. If you only post from your own domain then this is not important!
These rules ensure the message is not modified, and thus the original dkim signature from the sender should still be valid.
Upgrade to the latest surgemail release.
Do not use the subject_prefix setting
Do not add a footer with the footer settings.
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:
| listtalk archivetrue titleThe list for talkers. subject_prefix[list: talk] access_joinAnyone access_postModerator access_whoAnyone access_getAnyone moderatortalk.master@macro.com max_size40 footrc:\surgemail\dlist\talk\footer.txtlistjuggle titleThe list for jugglers. subject_prefix[Juggle] access_joinAnyone access_postAnyone access_whoAnyone access_getAnyone moderatorjuggling.master@macro.com max_size40 footerc:\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.comto 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.comwhere 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.