Sympa Logo
Translations of this page:

Customizing Sympa/WWSympa

Template file format

Template files within Sympa used to be in a proprietary format that has been replaced with the TT2 template format.

You will find detailed documentation about the TT2 syntax on the web site:

If you are an emacs user, you can use the TT2 highlighting mode by Dave Cross. Vim users should check out the vim-perl distribution which includes TT2 syntax files.

Here are some aspects regarding templates that are specific to Sympa:

  • References to PO catalogues are noted with the [% loc %] tag that may include parameters. Example:
    [%|loc(,]Welcome to list %1 %2[%END%]
  • Apart from a few exceptions, for security reasons templates cannot insert or parse a file given its full or relative path. Only the file name should be provided; the TT2 parser will then use the INCLUDE_PATH provided by Sympa to find the relevant file to insert/parse.
  • The qencode filter should be used if a template includes SMTP header fields that should be Q-encoded. Example:
    [% FILTER qencode %]Message à modérer[%END%]
  • You can write different versions of a template file in different languages, each of them being located in a subdirectory of the tt2 directory. Example: /mail_tt2/fr_FR/helpfile.tt2.
  • Your templates can include custom parameters.
· %2007/%06/%22 %17:%Jun ·

Custom actions

Starting Sympa 6.1, you can create your own actions, i.e. you can display any TT2 template in the Sympa web interface. These templates will be processed and completely integrated to Sympa, using its CSS and the data from the server.

Custom actions are used to run specific code and/or display user defined templates. They can be executed in list or global context (it is up to you to decide what to do in both cases). Previously, a custom action was a simple TT2 template added to the web interface. It could only display data, not process them. They were improved to allow greater expressiveness.


You can create a <your_action>.pm module under etc/custom_actions or etc/<robot>/custom_actions (This module must define a package called <your_action>_plugin) with a single process() sub to add custom processing. In list context you can also create it under expl(/<robot>)?/<list>/custom_actions. You can also create a <your_action>.tt2 file at the same place to display your template. You don't need the <head/> section or the <body/> tag.

Your custom action is reachable using URL:

param1, param2, etc. are parameters that can be later used by the custom action.

The HTML code in <your_action>.tt2 can make use of the parameters this way: [% cap.1 %] for the first parameter (param1 in the example URL above), [% cap.2 %] for the second one, and so on. If the module is not defined the template is simply displayed.

You can even have a robot-common <your_action>.pm module with a specific <your_action>.tt2 for each robot as the file (.pm or .tt2) is conducted in this order :

  • expl/<robot>/<list>/custom_actions (if list context and robot support)
  • expl/<list>/custom_actions (if list context and no robot support)
  • etc/<robot>/custom_actions (if robot support)
  • etc/custom_actions

The module process() sub receives @cap entries as arguments (the List object is prepended to the argument list in list context). The module process() sub return value can be either:

  • 1, to parse and display the custom action related tt2
  • <a global action name>, to display its template
  • ca:<other_custom_action>, to parse and display another custom action related tt2 - you can therefore do your own custom workflow inside Sympa.
  • a hash, which entries will override $param ones, in case “custom_action” or “next_action” are present they act as described above.

Example : (etc/custom_actions/

package foo_plugin;
sub process {
    my $arg = shift;
    return 'info' if(ref($arg) eq 'List'); # Show list info page if in list context
    return 'ca:bar' if($arg eq 'bar'); # Show bar custom action tt2 if first arg is "bar"
    return {name => 'John'} if($arg eq 'barbar'); # Show foo.tt2 (own tt2) after putting "John" under the key "name" in $param
    return {name => 'John', next_action => 'review'} if($arg eq 'barbarbar'); # Same thing, but showing review page
    return 1; # Just showing own tt2 (foo.tt2)
<h2>A test action</h2>
[% IF list %]
<p>liste: [% list %]</p>
[% END %]
<p>Custom action name: [% custom_action %]</p>
[% FOREACH param=cap %]
<li><b>[% param %]</b></li>
[% END%]

Here is the result:

Mail template files

These files are used by Sympa as service messages for several commands. These files are interpreted (parsed) by Sympa and respect the TT2 template format; every file has a .tt2 extension. See Template file format.

Sympa looks for these files in the following order (where <list> is the listname if defined, <action> is the name of the command, and <lang> is the preferred language of the user):

  • /home/sympa/list_data/<list>/mail_tt2/<lang>/<action>.tt2.
  • /home/sympa/list_data/<list>/mail_tt2/<action>.tt2.
  • /home/sympa/etc/<lang>/<action>.tt2.
  • /home/sympa/etc/<action>.tt2.
  • /home/sympa/etc/mail_tt2/<lang>/<action>.tt2.
  • /home/sympa/etc/mail_tt2/<action>.tt2.
  • /home/sympa/bin/etc/mail_tt2/<lang>/<action>.tt2.
  • /home/sympa/bin/etc/mail_tt2/<action>.tt2.

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

The variables listed below may be used in these template files. Note however that all list-related variables are available in a list context only.

  • [% sender %]: e-mail address of the sender;
  • [% return_path %]: Return-Path SMTP header of the message;
  • [% fromlist %]: From SMTP header of the message;
  • [% replyto %]: Reply-To SMTP header of the message ;
  • [% boundary %]: MIME parts separator calculated for service messages;
  • [% robot_domain %]: domain of a virtual host as defined in the host parameter;
  • [% list.lang %]: default language of the list;
  • [% %]: the list name;
  • [% list.domain %]: the domain the list is hosted by;
  • [% %]: the domain the list is hosted by;
  • [% list.subject %]: the subject of the list;
  • [% list.owner %]: an array containing the list owners address;
  • [% list.dir %]: The absolute path to the list's configuration directory;
  • [% %]: sympa email address local part;
  • [% %]: sympa default host domain name;
  • [% conf.sympa %]: sympa's complete email address;
  • [% conf.request %]: return address for bounces (sympa-request);
  • [% conf.listmaster %]: listmaster's email addresses;
  • [% conf.wwsympa_url %]: WWSympa's root URL;
  • [% conf.title %]: Host web page title;
  • [% conf.listmaster_email %]: listmaster'e-mail address local part;
  • [% conf.version %]: for global messages only! Sympa version number;
  • [% %]: user email address;
  • [% user.lang %]: user language;
  • [% user.gecos %]: user gecos field (usually his/her name);
  • [% user.password %]: user password;
  • [% %]: date when the user subscribed to this list;
  • [% subscriber.update_date %]: date when the user last updated her/his profile;
  • [% subscriber.bounce %]: subscriber's bounce rate;
  • [% subscriber.first_bounce %]: date when this subscriber had her/his first bounce.

Below is a short list of the mail templates distributed by Sympa ; you should have a look at the /home/sympa/bin/etc/mail_tt2/ directory content to have a better view of the customizeable mail templates. Note also that some list-related mail templates are described in the Mailing list definition/List template files section.


This file is sent in response to a HELP command. You may use additional variables:

  • [% is_owner %]: TRUE if the user is list owner;
  • [% is_editor %]: TRUE if the user is list editor.


File returned by the LISTS command. An additional variable is available:

  • [% lists %]: this is a hash table indexed by list names and containing lists' subjects. Only lists visible to the user (according to the visibility list parameter) are listed.


  These are the public lists for [conf->email]@[conf->domain]

  [% FOREACH l = lists %]
  [% l.key %]@[% %] : [% l.value.subject %] ([% l.value.topics.0 %])

  [% END %]


This file is sent in response to a REMIND * command. (see Owner commands) You may use additional variables:

-[% lists %]: this is an array containing the names of the lists the user is subscribed to.


  This is a subscription reminder.

  You are subscribed to the following lists:
  [% FOREACH l = lists %]

   [% l %]: [% conf.wwsympa\_url \%]/info/[% l %]

  [% END %]

  Your subscriber e-mail: [% %]
  Your password: [% user.password %]


This message is sent to warn the sender of a virus infected mail, indicating the name of the virus found (see Antivirus).


This template includes most error messages related to message distribution.

Additional TT2 variables can be used within this template :

  • [% original_msg.full %]: the full original message
    * [% original_msg.body %]: the body of the original message
  • [% original_msg.from %]: the From header field of the original message
  • [% original_msg.subject %]: the Subject header field of the original message
  • [% original_msg.message_id %]: the Message-id header field of the original message

Web template files

You may define your own web template files, different from the standard ones. WWSympa first looks for list specific web templates, then for site web templates, before falling back on its defaults.

Your list web template files should be placed in the /home/sympa/list_data/mylist/web_tt2 directory, and your site web templates in the ~/home/sympa/etc/web_tt2 directory.

The easiest way to find out which variable are made available by Sympa is to switch the Set template vars dump feature on from the Sympa admin web page (you need to log in with listmaster privileges). You can check the list of available variables in each web page.

Sympa colors customization guide

Sympa colors are managed using color_x parameters in Sympa.conf.

You will find below how these parameters are interpreted in the Sympa web interface. Note that if you activated the static CSS, you will need to hit the “install static css” button once again to see the changes in your color definitions.

Sympa version 6 include a color editor in the “Sympa admin” systeme (see skins and css section)

Install time: web colors are defined in Sympa's main Makefile (see Compilation and installation).

What are the colors used for?

  • color_0: background color of:
    • one out of two lines in tables, alternated with color_5. It is intended to be the darkest shade, as color_5 has other uses.
  • color_1: background color of:
    • main navigation tabs
    • most of the buttons (those corresponding to the MainMenuLinks CSS class)
  • color_2: font and border color of:
    • almost everything. Exceptions for borders are <TD/> borders; exceptions for fonts are links, buttons and some titles.
  • color_3: background color of:
    • top box
    • footer box
  • color_4: background color of:
    • page
    • table headers (at the very exception of the table displaying new lists)
    • the rest of the buttons (which are in fact hyperlinks, corresponding to the actionMenuLinks CSS class)
  • color_5: background color of:
    • all the main interface boxes
    • the lightest color for the table lines, contrasting with color_0
  • color_6: background color of:
    • active action (for example, the section of the admin options which is currently viewed, or the header corresponding to the data following which an array is currently sorted)
    • hovered actions
    • hovered buttons corresponding to the actionMenuLinks CSS class
    • hovered navigation tabs
  • color_7: background color of:
    • error messages
    • just edited area in the administrative management section.
  • color_8: doted underscore color of:
    • hyperlinks
  • color_9:
    • border color for active action (for example, the section of the admin options which is currently viewed, or the header corresponding to the data following which an array is currently sorted)
    • border color for hovered hyperlinks corresponding to actions
    • background color for clicked links (corresponding to the .active state in a CSS)
  • color_10: inactive buttons color. Rarely used. Don't bother.
  • color_11: font color for:
    • active navigation tab
    • H2 titles
    • hovered links
    • some hovered buttons action(which are in fact hyperlinks, corresponding to the actionMenuLinks CSS class)
  • color_12: Font color for the class smallblack. Not sure it is used.
  • color_13: Background color of:
    • editable form areas (text areas, selection lists, ...)
    • the rest of hovered buttons (those corresponding to the MainMenuLinks CSS class)
  • color_14: Unused
  • color_15: Unused

What colors do the objects have?

Here are gathered informations about the color parameters used for specific parts of the web interface. Take care to have a look to the preceding section as changing a parameter for an object is likely to change it for a few similar objects.

Main backgrounds

There are four different backgrounds in the web interface:

  • The page: color_4; below all the rest. Just the base on which all the rest is stacked.
  • The main boxes: color_5; This is where most of the text, buttons and links are displayed.
  • The top box and footer: color_3; the top box is where your service name and main navigation tabs are displayed. The footer contains the version of Sympa.
  • The editable forms areas: color_13; This is the color in all the form widgets which can be edited by users (text areas, selection lists).


The buttons color management can be confusing, so let's just stress it a little:

Color attribute MainMenuLinks CSS classactionMenuLinks CSS class
Default background colorcolor_1color_4
Hovered background colorcolor_13color_6
Default font colorcolor_2color_2
Hovered font colorcolor_1color_11
Default border colorcolor_2color_2
Hovered border colorcolor_2color_2


Hyperlinks have the same attributes as plain text, except:

  1. They are always underscored by a doted line of color color_8
  2. When hovered, they take the color color_11

Menu links

They have the following attributes:



Note these additional informations:

  1. navigation tabs have the same default parameters as the class MainMenuLinks but the same parameters as actionMenuLinks when hovered;
  2. except for the MainMenuLinks button, anything likely to do something if clicked takes the font color color_11 when hovered;
  3. the menu links (Info, Admin, Edit list config...) are the only objects whose color actually changes on click.

For some basic color schemes:

Add this line to sympa.conf:

Color customizations

for bright red background, (sunglasses may be required!)

color_4 #FF3366

for bright green background

color_4 #00CC00

CSS files

Sympa has four CSS stylesheets : style.css, print.css, print-preview.css and fullPage.css.

It will use a stylesheet or the other regarding the kind of request the user addressed.

But, for each stylesheet, what is sent to users varies regarding the values of two parameters : css_path and css_url.

css_path and css_url parameters

  • css_path defines the directory in which wwsympa can find static CSS files;
  • css_url defines the URL used by web clients to request the web server for stylesheets.

These parameters values are looked for in robot.conf first, then sympa.conf, and then, if not found, set to hard-coded defaults.

  • If css_path isn't defined, its default is set to : ${static_content_path}/css. static_content_path is the parameter defining the root path to all static content for Sympa. If static_content_path is undefined in sympa.conf or robot.conf, its value is set to : sympa_home_dir/static_content.
  • If css_url isn't defined, its default is set to : ${static_content_url}/css. static_content_url is the parameter defining the root url to all static content in Sympa. If static_content_url is undefined in sympa.conf or robot.conf, its value is set to : /static-sympa.

This way :

  • the default path to static stylesheet is : sympa_home_dir/static_content/css/style.css

The script, run at install, can set both static_content_path and static_content_url values.

What stylesheet will be used ?

  • Case 1 : if the directory defined by css_path exists, the value of css_url will be the one defined in Sympa config.
  • Case 2 : if this directory doesn't exist, the value of css_url will be that of the css action (i.e.

The content delivered varies greatly according to which case happens.

  • Case 1: the stylesheet received by the client is the file found in the directory that your Apache server configuration associates to this URL. It is up to you to decide whether this directory must correspond to the css_path value or not. If it corresponds to the css_path value, you must use the files generated by wwsympa. If not, you will use whichever stylesheet you want to define. Whatever solution you choose, take note that wwsympa will not, opposite to case 2, be involved in the stylesheet delivery, as it won't be addressed the HTTP request. This way, your stylesheet is served directly by Apache and remains in cache, thus saving bandwidth.

  • Case 2: the stylesheet received by the client is the result of a wwsympa action called css. wwsympa parses a file named css.tt2 that it finds in the relevant web_tt2 folder and generates on the fly a stylesheet that it returns to the client. In this case, the action is triggered any time a page is requested to wwsympa and the four stylesheets are sent along with the page. This is more bandwidth consuming than case 1, but any change in css.tt2 will be applied at once, without static content generation. This is particularly usefull when experimenting a new stylesheet.

If you use virtual hosts: this section describes all the possibles configuration options and their consequences on the actual paths and URL used.

Using wwsympa CSS generation process

The CSS generation described in the case 2 of the previous section has two purposes :

  • Serve CSS files generated on the fly for each request
  • Generate static CSS files stored in the directory defined by the css_path parameter. These files are subsequently used as static content. The static CSS file generation can be done in two ways :
    • using the “Install static CSS” button in the skins administration page of wwsympa.
    • automatically updated at process startup whenever it detects that the static CSS is older than the css.tt2 template file. This is very convenient while doing a Sympa upgrade because the static CSS files get automatically updated. The listmaster gets a mail notification.

The following explanations apply whichever you use static (but sympa-generated) or dynamic CSS. Both operations use the same template file and data.

  • Colors are defined in either sympa.conf or robot.conf. The role of each color parameter is explained in the color customization guide. For the particular case of colors, though, note that the colors used are those from the robot.conf or sympa.conf, whichever is relevant. wwsympa uses those loaded in memory at the time the CSS generation is requested, being to generate a static stylesheet or to deliver a dynamic one directly. That means that if you change colors in your configuration file, these changes must be taken into account by wwsympa prior to regenerating CSS.
  • Any other CSS information is defined in css.tt2 template. As any other template, take care not to modify the default file (in sympa_home/bin/etc/web_tt2) but to copy it in sympa_home/etc/web_tt2 or sympa_home/etc/robot_dir/web_tt2 and modify the copies. In these copies, you can add/change/delete anything you like, it is not supposed to suffer from upgrades.

Use custom stylesheets only

Nothing prevents you from configuring your Apache server in order that requests to URL containing css_url be answered by serving the content of a directory different from the one corresponding to css_path. This way, you can directly edit the style.css file, and this file won't be overwritten during the next update. The drawback is that you can't use the color_x parameters defined in your robot.conf/sympa.conf file. Indeed, they are used only when parsing css.tt2.



WWSympa's homepage shows a list of topics for classifying mailing lists. This is dynamically generated using the different lists' topics configuration parameters. A list may appear in multiple categories.
This parameter is different from the msg_topic parameter used to tag list messages.

The list of topics is defined in the topics.conf configuration file, located in the /home/sympa/etc directory. The format of this file is as follows:

  title    <topic1 title> <topic french title>
  visibility <topic1 visibility>
  title    <topicn title> <topicn german title>

You will notice that subtopics can be used, the separator being /. The topic name is composed of alphanumerics (0-1a-zA-Z) or underscores (_). The order in which the topics are listed is respected in WWSympa's homepage. The visibility line defines who can view the topic and subtopics. It refers to the associated topics_visibility authorization scenario. You will find a sample topics.conf in the sample directory; NONE is installed as the default.

A default topic is hard-coded in Sympa: default. This default topic contains all lists for which a topic has not been specified.

Authorization scenarios

List creation templates

Custom parameters

You can create an unlimited number of custom parameters to be used with authorization scenarios, web templates and mail templates.

These parameters are defined in each list configuration through the web interface by using the form in Admin → Edit list config → Miscellaneous page. There, you add a parameter in the custom parameters (custom_vars) section. The var name field corresponds to your custom parameter name, the var value field corresponds to your custom parameter value.

You can later access this parameter:

  • in scenarios : with the syntax [custom_vars->your_custom_var_name]
  • in web or mail templates : with the syntax custom_vars.your_custom_var_name


You define a custom parameter with the following values:

  • var name : sisterList
  • var value : math-teachers

You can use it as follows:

  • in scenarios : with the syntax [custom_vars->sisterList], which will correspond to “math-teachers”
  • in web or mail templates : with the syntax custom_vars.sisterList, which will correspond to “math-teachers”

Custom user attributes

If the user description parameters available in Sympa don't suit your needs, you can define your own description attributes. These attributes can be used when moderating subscription or message moderation. They provide additional, useful informations, when making a decision.

Custom attributes definition

These attributes are defined in the list configuration by the custom_attribute list parameter.
You can define as many attributes as you like.

Custom attributes provisionning

Custom attributes can be provionned using two mutually exclusive ways:

  1. manually by the user
  2. extracted from and LDAP or SQL repository.

How are the custom attributes values obtained from users?

Users can provide the information expected by your custom attributes on two occasions :

  • when subscribing to the list through the web interface. After hitting the “subscribe” button, the user is presented a form, each field of which corresponds to a custom attribute.

  • when modifying their profile through the web interface.

How is it stored?

The custom attributes are stored as XML fragments in the subscriber_table table. This fragment is located in the custom_attribute_subscriber field.

Here is an example of such an XML fragment, which contains two custom attributes :

  • the first one has the id “accr” and has the value “ultra-violet”;
  • the second one has thee id “pt” and has the value “0”.
<?xml version="1.0" encoding="UTF-8" ?>
    <custom_attribute id="accr">
      <value> ultra-violet</value>
    <custom_attribute id="pt">

So, what can you do with that feature?

the custom attributes are displayed for each user in the subscribers review of the web interface.

You can use these attributes to customize messages.

Loop detection

Sympa uses multiple heuristics to avoid loops in Mailing lists.

First, it rejects messages coming from a robot (as indicated by the From: and other header fields) and messages containing commands.

Second, every message sent by Sympa includes an X-Loop header field set to the listname. If the message comes back, Sympa will detect that it has already been sent (unless X-Loop header fields have been erased).

Third, Sympa keeps track of Message IDs and will refuse to send multiple messages with the same message ID to the same mailing list.

Finally, Sympa detect loops arising from command reports (i.e. sympa-generated replies to commands). This sort of loop might occur as follows:

  • X sends a command to Sympa
  • Sympa sends a command report to X
  • X has installed a home-made vacation program replying to messages
  • Sympa processes the reply and sends a report
  • Looping to step 3

Sympa keeps track (via an internal counter) of reports sent to any particular address. The loop detection algorithm is:

  • increment the counter
  • If we are within the sampling period (as defined by the loop_command_sampling_delay parameter)
    • If the counter exceeds the loop_command_max parameter, then do not send the report, and notify listmasters
    • Else, start a new sampling period and reinitialize the counter, i.e. multiply it by the loop_command_decrease_factor parameter


manual/customizing.txt · Last modified: 2017/10/17 13:47 by

The Sympa software is provided by RENATER
Faq | News | Contact | Legal Notices