TemplateHowto

TMDA Template HOWTO

---

Introduction

TMDA comes with a set of template files which hold the content used in its various auto-responses. You can customize this content by editing and maintaining your own set of templates, which will be explained below.

If you downloaded a TMDA source tarball, these files will be located in the templates/ subdirectory of the distribution. If you are using a TMDA package, the template files will be in a global directory such as /etc/tmda/, /usr/share/tmda/ or /usr/local/share/tmda/.

There are currently three sets of templates for TMDA's three different types of auto-responses -- "bounce" (failure notices), "confirm request" (delivery confirmation requests), and "confirm accept" (delivery confirmation notices). The table below details what each template file is used for. You'll also get a good sense of what each template does by just looking at their contents.

---

Template structure

TMDA templates look much like a standard RFC 2822 e-mail message, consisting of header fields followed by a message body. The body is separated from the header by an empty line.

header

Header fields are lines composed of a field name, followed by a dot ("."), followed by the name of the header's character set, followed by a colon (":"), followed by a field value, and terminated by CRLF. e.g,

Subject.US-ASCII: Please confirm your message

Header fields and values MUST be composed of printable US-ASCII characters. See the International section below if you wish to use non-ASCII characters in your template header values.

body

The body of a message is simply lines of US-ASCII characters. See the International section below if you wish to use non-ASCII characters in your template body.

composition

Templates are composed of plain text mixed with variables in the form %(variable)s. The values of these variables are strings which are filled in when the message is created from the template. Variables can come from a variety of places:

1. Any variables in the Defaults.py namespace (usually shown in all caps in the templates).
2. Any variable set in the bouncegen() function of tmda-rfilter (usually in all lowercase in the templates). You'll have to look at the source for bouncegen() if you want a full list of these.

3. Any variable set in your ~/.tmda/config or in /etc/tmdarc. For example, my config stores a local weather report in the variable la_weather', which I then reference in my custom template as %(la_weather)s`.

---

Customizing your templates

The contents of the default templates will suit the needs of some users, but many will want to customize them. TMDA makes this easy to do.

If you want to use customized templates, you define TEMPLATE_DIR in your ~/.tmda/config, and copy the default templates that you want to customize to that directory. Another option is to invoke tmda-filter with the -t option. Then edit the template(s) to suit your needs.

If a template is not found in your custom directory, the default template will be used. This allows you for example to only customize confirm_request.txt, taking the defaults for the other templates.

If you want to use particular custom templates for a specific sender address, or sender addresses in a specific sub-domain or top-level domain, see the TEMPLATE_DIR_MATCH_SENDER feature. TEMPLATE_DIR_MATCH_RECIPIENT offers a similar feature based on the recipient address.

---

International templates

The default templates are written entirely in English, and in US-ASCII. If your native language is not English, and you frequently correspond with other users of that language, you may wish to use multilingual templates. TMDA also allows you to do this fairly easily.

NOTE: It's recommended that you not remove the English content from your templates, but rather supplement it with a native language translation. For better or worse, the common language of the Internet is English, and to insure maximum readability, you should adhere to this.

If your language does not use non-ASCII characters, you can safely ignore the rest of this section. However, if you do wish to use non-ASCII characters in your templates such as the cedilla in French or umlauts in German, keep reading.

International e-mail primer

Internet e-mail was born at a time when most e-mail was composed of 7-bit ASCII characters only. Of course, as e-mail has been deployed worldwide, it has become internationalized, such that language specific character sets can now be used in email messages. The base standard still requires e-mail messages to be transfered using only 7-bit ASCII characters, so a slew of RFCs have been written describing how to encode email containing non-ASCII characters into an RFC 2822-compliant format.

Luckily, TMDA handles all these gory details for you. This means you can write your templates in the character set of your choice, and TMDA will make sure the resulting auto-response is RFC-compliant.

Internationalized bodies

If you wish to use non-ASCII characters in the body of your template, first change the value of the BodyCharset pseudo-header field to the character set covering your language. Refer to the table at the bottom of this page for help figuring out which character set to use.

For example, if you are mixing German+English in your template, BodyCharset should be set to the following:

BodyCharset: LATIN-1

Then just enter the non-ASCII characters directly into your template along with the ASCII characters. TMDA will properly encode the message based on the charset you specified.

BodyCharset only accepts one charset as its value, so you should choose a character set that encompasses all the languages you plan to use in your template. For example, you can write German+Polish+English with LATIN-2 or German+Turkish+English with LATIN-5 but there is no 8-bit charset to properly mix German+Russian+English, for instance.

The entire BodyCharset field is case-insensitive. If BodyCharset is not provided, it defaults to US-ASCII.

Internationalized headers

If you wish to use non-ASCII characters in your template header values, first change the charset suffix for that header to the character set covering your language. Refer to the table at the bottom of this page for help figuring out which character set to use.

For example, if you want to use a German Subject in your template, the Subject field might be changed to the following:

Subject.LATIN-1: Please confirm your message / Bitte Bestätigen

Unlike template bodies, template headers are not restricted to one character set. Different headers can use different character sets. For example, a Japanese From field with German Subject field:

From.EUC-JP: "藤原誠 / Makoto Fujiwara" <%(recipient_address)s>
Subject.LATIN-1: Please confirm your message / Bitte Bestätigen

If a charset suffix is not provided, it defaults to US-ASCII for that header.

CJK (Chinese, Japanese, Korean)

Multi-byte character sets such as those used in CJK can be used in a TMDA template, but requires that the proper Unicode codec be installed into your Python (single-byte 8-bit charsets don't need a Unicode codec).

You must first install the CJKCodecs Python package if you are running Python 2.3.x. The latest version of the package at this writing is 1.1.1. CJKCodecs has been integrated into Python 2.4 so if you are running that version, you do not need to install the separate package.

• Simplified Chinese (China): Your templates must be saved in the GB2312 charset.

• Traditional Chinese (Taiwan): Your templates must be saved in the BIG5 charset.

• Japanese: Your templates must be saved in the EUC-JP charset, not ISO-2022-JP or Shift_JIS. When the e-mail message is sent, the text will be automatically be convered into ISO-2022-JP for reliable 7-bit transmission.

• Korean: Your templates must be saved in the EUC-KR charset.

Choosing the right character set

The charset value for BodyCharset, and the charset suffix in Header.CHARSET: can be any standard character set name (such as ISO-8859-1), or an alias for that charset (such as LATIN-1). Charset names and aliases are case-insensitive.

All charsets are supported, but here is a table listing some of the more popular ones, along with their alias (if any), and some languages covered by that charset.

Also see Roman Czyborra's excellent ISO 8859 Alphabet Soup for more on the ISO 8859 series (which will cover most user's I18N needs).