This chapter describes what a mailing list is made of within a Sympa environment.

See list aliases section, Mail aliases.

The configuration file for the mylist list is named /home/sympa/list_data/my.domain.org/mylist/config (or /home/sympa/list_data/mylist/config if no virtual host is defined). Sympa reloads it into memory whenever this file has changed on disk. The file can either be edited via the web interface or directly via your favourite text editor.

If you have set the cache_list_config sympa.conf parameter (see cache_list_config), a binary version of the config (/home/sympa/list_data/my.domain.org/mylist/config.bin is maintained to allow a faster restart of daemons (this is especialy useful for sites managing lots of lists).

Be careful to provide read access for Sympa user to this file!

You will find a few configuration files in the sample directory.

List configuration parameters are described in the list creation section, List configuration parameters.

This first example is for a list open to everyone:

  subject First example (an open list)

  visibility noconceal

  owner
  email Pierre.David@prism.uvsq.fr

  send public

  review public

The second example is for a moderated list with authenticated subscription:

  subject Second example (a moderated list)

  visibility noconceal

  owner
  email moi@ici.fr

  editor
  email big.prof@ailleurs.edu

  send editor

  subscribe auth

  review owner

  reply_to_header
  value list

  cookie 142cleliste

The third example is for a moderated list, with subscription controlled by the owner, and running in digest mode. Subscribers who are in digest mode receive messages on Mondays and Thursdays.

  owner
  email moi@ici.fr

  editor
  email prof@ailleurs.edu

  send editor

  subscribe owner

  review owner

  reply_to_header
  value list

  digest 1,4 12:00

Be careful: since version 3.3.6 of Sympa, a RDBMS is required for internal data storage. Flat files should not be use anymore except for testing purpose. Sympa will not use these files if the list is configured with include, database or user_data_source.

The /home/sympa/list_data/mylist/subscribers file is automatically created and populated. It contains information about list subscribers. It is not advisable to edit this file. Main parameters are:

• email address
  Email address of the subscriber.
• gecos data
  Information about the subscriber (last name, first name, etc.) This parameter is optional at subscription time.
• reception | nomail | digest | summary | notice | txt | html | urlize | not_me
  Special delivery modes which the subscriber may select. Special modes can be either nomail, digest, summary, notice, txt, html, urlize and not_me. In normal delivery mode, the delivery attribute for a subscriber is not displayed. In this mode, subscription to message topics is available. See the SET LISTNAME SUMMARY command, the SET LISTNAME NOMAIL command and the digest parameter.
• visibility conceal
  Special mode which allows the subscriber to remain invisible when a REVIEW command is issued for the list. If this parameter is not declared, the subscriber will be visible for REVIEW. Note: this option does not affect the results of a REVIEW command issued by an owner. See the SET LISTNAME CONCEAL command for details.

/home/sympa/list_data/mylist/info should contain a detailed text description of the list, to be displayed by the INFO command. It can also be referenced from template files for service messages.

/home/sympa/list_data/mylist/homepage is the HTML text on the WWSympa info page for the list.

Every file has the .incl extension. Moreover, these files must be declared in paragraphs owner_include or editor_include in the list configuration file (without the .incl extension) (see List configuration parameters). This files can be template files.

Sympa looks for them in the following order:

1. /home/sympa/list_data/mylist/data_sources/<file>.incl;
2. /home/sympa/etc/data_sources/<file>.incl;
3. /home/sympa/etc/my.domain.org/data_sources/<file>.incl.

These files are used by Sympa to load administrative data in a relational database: owners or editors are defined intensively (definition of criteria owners or editors must satisfy). Includes can be performed by extracting email addresses using an SQL or LDAP query, or by including other mailing lists.

A data inclusion file is made of paragraphs separated by blank lines and introduced by a keyword. Valid paragraphs are include_file, include_remote_file, include_list, include_remote_sympa_list, include_sql_query, include_ldap_2level_query and include_ldap_query. They are described in the List configuration parameters chapter.

When this file is a template, the variables used are array elements (param array). This array is instantiated by values contained in the subparameter source_parameter of owner_include or editor_include.

Example:

• in the list configuration file /home/sympa/list_data/mylist/config :

        owner_include
        source myfile
        source_parameters mysql,rennes1,stduser,mysecret,studentbody,student

• in /home/sympa/etc/data_sources/myfile.incl:

        include_sql_query
        db_type [% param.0 %]
        host sqlserv.admin.univ-[% param.1 %].fr
        user [% param.2 %]
        passwd [% param.3 %]
            db_name [% param.4 %]
        sql_query SELECT DISTINCT email FROM [% param.5 %]

• once it has been parsed with provided parameters, the inclusion directives would look like this:

        include_sql_query
        db_type mysql
        host sqlserv.admin.univ-rennes1.fr
            user stduser
            passwd mysecret
            db_name studentbody
            sql_query SELECT DISTINCT email FROM student

These files are used by Sympa as service messages for commands such as SUB, ADD, SIG, DEL, REJECT. These files are interpreted (parsed) by Sympa and respect the template format; every file has the .tt2 extension. See Template file format.

Sympa looks for these files in the following order:

1. /home/sympa/list_data/mylist/mail_tt2/<file>.tt2;
2. /home/sympa/etc/mail_tt2/<file>.tt2;
3. /home/sympa/bin/etc/mail_tt2/<file>.tt2.

If the file starts with a From: line, it is considered to be a full message and will be sent (after parsing) without the addition of SMTP headers. Otherwise the file is treated as a text/plain message body.

The following variables may be used in list template files:

• [% conf.email %]: Sympa email address local part;

• [% conf.domain %]: Sympa's robot domain name;

• [% conf.sympa %]: Sympa's complete email address;

• [% conf.wwsympa_url %]: WWSympa's root URL;

• [% conf.listmaster %]: listmasters' email addresses;

• [% list.name %]: list name;

• [% list.host %]: list hostname (default is Sympa robot domain name);

• [% list.lang %]: list language;

• [% list.subject %]: list subject;

• [% list.owner %]: list owners table hash;

• [% user.email %]: user email address;

• [% user.gecos %]: user gecos field (usually his/her name);

• [% user.password %]: user password;

• [% user.lang %]: user language;

• [% execution_date %]: the date when the scenario is executed.

You may also dynamically include a file from a template using the [% INSERT %] directive.

Example:

  Dear [% user.email %],

  Welcome to list [% list.name %]@[% list.host %].

  Presentation of the list:
  [% INSERT 'info' %]

  The owners of [% list.name %] are:
  [% FOREACH ow = list.owner %]
     [% ow.value.gecos %] <[% ow.value.email %]>
  [% END %]

Sympa will send a welcome message for every subscription. The welcome message can be customized for each list.

Sympa will send a farewell message for each SIGNOFF mail command received.

This message is sent to users who have been deleted (using the DELETE command) from the list by the list owners.

Sympa will send a reject message to the senders of messages rejected by the list editors. If they prefixe their REJECT with the keyword QUIET, the reject message will not be sent.

This message is sent to users who have been invited (using the INVITE command) to subscribe to a list.

You may use additional variables

• [% requested_by %]: email of the person who sent the INVITE command;

• [% url %]: the mailto: URL to subscribe to the list.

This file contains a message sent to each subscriber when one of the list owners sends the REMIND command.

Template for summaries (reception mode close to digest), see the SET LISTNAME SUMMARY command.

Template that defines list mail alises. It is used by the alias_manager script.

Note that this template is not a service messages, therefore it is not located in a mail_tt2/ subdirectory.

/home/sympa/list_data/mylist/stats is a text file containing statistics about the list. Data are numerics separated by white space within a single line:

• number of messages sent, used to generate X-sequence headers;
• number of messages X number of recipients;
• number of bytes X number of messages;
• number of bytes X number of messages X number of recipients;
• number of subscribers;
• last update date (epoch format) of the subscribers cache in DB, used by lists in include2 mode only.

These files are used by Sympa to create task files. They are interpreted (parsed) by the task manager and respect the task format. See Tasks.

Every year Sympa will send a message (the template remind.tt2) to all subscribers of the list to remind them of their subscription.

Every month Sympa will delete subscribers older than one year who haven't answered two warning messages.

You may create the /home/sympa/list_data/mylist/message.header and /home/sympa/list_data/mylist/message.footer files. Their content is added, respectively at the beginning and at the end of each message before the distribution process. You may also include the content-type of the appended part (when footer_type list parameter is set to mime) by renaming the files to message.header.mime and message.footer.mime.

The footer_type list parameter defines whether to attach the header/footer content as a MIME part (except for multipart/alternative messages), or to append them to the message body (for text/plain messages).

Under certain circumstances, Sympa will NOT add headers/footers, here is its algorythm:

  if message is not multipart/signed
          if footer_type==append
              if message is text/plain
                 append header/footer to it
          else if message is multipart AND first part is text/plain
                 append header/footer to first part

          if footer_type==mime
              if message is not multipart/alternative
                 add header/footer as a new MIME part

The /home/sympa/list_data/mylist/archives/ directory contains the messages archived for lists which are archived; see archive. The files are named in accordance with the archiving frequency defined by the archive parameter.