Title: Common TeamPage Server Mailbox Configuration
Traction TeamPage Release 4.2 added a new option to receive and log email: TeamPage can read email from a single POP or IMAP mailbox and route the email content to a space - or add the email as a comment to an existing article - based on a set of configurable rules. If you already have configured some TeamPage spaces to read a dedicated per-space email address that still works, but you can now use a single mailbox with one email alias per space and routing rules to accomplish the same thing with less administrative overhead.
Configuration
The Server Mailbox Configuration controls are on the Server Setup > Email page's Incoming Email tab.
The Basic tab has controls for enabling the Server Mailbox, setting the mailbox poling interval, and supplying an administrator email address that is used as the From address for bounce messages in case the user who sent the message doesn't have permission to post the resulting article.
Use the Account Information tab to set the login credentials for the mailbox, as well as the email address and friendly name that are set in the Reply-To field of email notification messages. The specified email address is also advertised in certain places in the TeamPage UI.
The protocol and server address, as well as other protocol-specific connection details, must be entered on the Server Information tab.
After you have entered at least the login credentials and server connection details for the mailbox, you can apply the changes and test that the TeamPage server can open the mailbox. Don't forget to test the connection before you leave the Server Setup > Email page!
The Filters & Rules tab has several advanced settings relating to routing, filtering and tagging articles created from messages sent to the server mailbox. The Mail Routing Rules and Catch-All Space settings are covered below. The Mail Filters setting allows you to select which "filters" to apply. These filters each correspond to a Java class that has a chance to examine and make modifications to the article or comment being created from an email message. The mail filter mechanism is extensible. The Email Alias Rules and Email Header Rules settings allow tagging of new articles created from email messages based upon the recipient addresses and the values of other message headers.
Types of Routing Rules
Mail Routing Rules and Catch-All Space
The Mail Routing Rules setting can be particularly important if your server mailbox has many aliases, because these aliases can be used to derive the target space based upon the address to which the message was originally sent. See, for example, these rules defined on this server:
These rules may seem difficult to understand at first, but they are fairly straightforward.
Both rules have "Recipient" in the "Route messages with a header field" column. "Recipient" doesn't refer to a real field, but is instead expanded to refer to the fields "To" and "Cc"; and, to support sending messages via Bcc (which is, of course, not available in the received message since it represents a blind carbon copy), also the "X-Original-To" and "Delivered-To" fields, which are used by various mail servers to indicate the actual recipient address and/or mailbox name. You can use any header name you want in this field, such as "To", "Cc", "Subject". You can also use "Bcc" to refer to the "X-Original-To" and "Delivered-To" fields. The case of the header name is ignored, so that, e.g., "Cc" and "cc" are equivalent.
In the first rule, the regular expression in the "which matches the regular expression" column is
(.+)_journal@.*
The mailbox inbox@tractionserver.com has many aliases, including <space-name>_journal@tractionserver.com for many spaces. It also has aliases involving other host names since the server has multiple host names (and also receives messages that are redirected from addresses on other mail servers), so we use .* after the @ symbol to match any IP address or host name. The space name is given as $1 because that corresponds to the first grouping of parentheses in the regular expression pattern. This allows us to dynamically extract the space name from the address to which the message was originally sent. $1 refers to everything before the _ character; for example, help_journal@tractionserver.com is routed to the Help space.
In the second rule, the regular expression is
inbox[+](.*)@.*
Sending a message to an address of the form <address>+<extension>@<server> is a commonly supported email routing notation to have a message really addressed to <address>@<server>, but with an additional sub-address extension after the + and before the @ -- a built-in feature of the email standard that can be used for routing and filtering of exactly the type that is being done here. Note that not all servers support this feature. But if the mail server hosting your server mailbox does support this feature, you can use a format like we have, of inbox+<space-name>@tractionserver.com, and to capture the <space-name> component just as in the first rule, again using $1 to refer to the first capture group.
You may wish to create rules based upon other message headers, or more complicated formulas involving capture groups in your regular expressions -- or less complicated formulas if, for example, you want a static routing to a single space if a certain expression is matched.
The Catch-All Space setting is kind of the routing rule of last resort: if no other routing rule is matched -- either a custom routing rule or a standard routing rule (see below), the message will be routed to the catch-all space if one is selected. By default, messages that have no routing but which are from a known user account are bounced back to the sending address. Messages that cannot be correlated with a user account are treated as Visitor, and are not bounced.
Note that whatever routing rule is applied, the authoring user and the target space are figured out first, and tests for whether the user is allowed to post the requested entry in the target space are performed later. In other words, if a routing rule is matched, the sender of the email must have permission to Author by Email in the space selected by the built-in or configurable rules - if that user does not have permission, the email message will be either posted to the catch-all space if one is selected, or bounced.
Tip: Even though you can specify a space by putting @spacename in the subject line of a message, there are a few good reasons to to give each space its own unique email address using Mail Routing Rules like the ones in the example above. Firstly, this allows users to easily add a single address to their address book corresponding to a single space. Secondly, it allows the creation of simple mailto: links in documents that may appear outside of your TeamPage server. You could add such a link to a web page or other hypertext document to allow people reading that page to simply click to send a message to a given space. Thirdly, if you want advanced users to be able to send a message, particularly using the Bcc field, to a single space but without having to put a routing directive in the subject, having a dedicated email address or alias for that space is the ideal way to do so.
If you do use custom routing rules, it is recommended to use rules like those in the example that effectively create email aliases for each space in a consistent fashion.
Standard Routing Rules
Subject Header Commands
One set of standard message routing rules are based upon "commands" that users can insert into the subject header of the message (see also Sending Email to TeamPage which explains these, and other available commands, for end users):
@spacename The new article will be posted as a new article in the space given by spacename.
@spacename# The new article will be posted as a comment on article spacename#. Use, for example, MarketResearch2470 for article 2470 in the MarketResearch space. If no space directive is specified using the @spacename syntax, the new article will be posted in the moderation space for the target article's space. To post a comment, the user must have both Comment and Author by Email permissions in the target space.
@spacename#.i The new article will be posted as a comment on item i in the article spacename#. The value for i must contain a leading 0 to indicate that it targets an item by its ID, not its number. Use, for example, MarketResearch2470.05 for paragraph ID 5 in article 2740 in the MarketResearch space.
Reply-Chain Correlation
TeamPage also examines the "In-Reply-To" and "References" headers of a message in the server mailbox to determine whether the message is a reply to an existing entry. The correlation is possible because entries in the journal that are associated with an email message (that were created either from an incoming message or created in conjunction with an outgoing email message using the Email Reply or Email Articles features) all have a Message-Id header that uniquely identifies the associated message. If a reply target entry is found, the message can be routed to the moderation space of the entry.
Routing Rule Order and Precedence
Routing rules are applied in a particular order; but some that are applied later may take precedence over some applied earlier. Please read the following steps carefully to understand how rules are applied. Each time "save the resulting routing" note that it overrides any routing saved in a previous step.
1. Apply rules defined in the Mail Routing Rules setting one at a time in order; if a match is found, save the resulting routing and skip the remaining rules and proceed to step 2.
2. (If a special type of entry has been designated in the subject, e.g., a task via the "task:" prefix, this rule may not apply. See Sending Email to TeamPage.) Apply the reply target Subject Header Command routing rule (@spacename# and @spacename#.i -- both of these variations are applied at the same time), as many times as valid matches are found. The left-most matches are recognized first, and subsequent matches are performed against only the remaining text. At each match, save the resulting reply target; also save the resulting routing (targeting the reply target space's moderation space). The last routing "wins," and its text is removed from the message subject (later to be used as the new entry's title).
3. Apply the target space Subject Header Command routing rule (@spacename). As with step 2, the rule is applied as many times as there are valid matches, with left-most matches recognized first, and subsequent matches performed against only the remaining text. At each match, save the resulting routing. Again, as in step 2, the last routing "wins," and its text is removed from the subject to be used as the new entry's title.
4. If a routing has been saved by this point, skip to step 7.
5. Apply the Reply-Chain Correlation routing rule. Handle the "In-Reply-To" header first, then each "References" header in turn. If an existing entry is found that has the same value for its "Message-Id" field, save the resulting routing (targeting the reply target space's moderation space), and skip to step 7.
Note that only one "In-Reply-To" header is allowed, so only the first one will be scanned even if there are more than one. Multiple "References" headers are allowed, and they are scanned in the order in which they appeared in the original message. Note also that no reply target was saved at this step; reply-chain correlation is done automatically by the TeamPage system at the time an entry is created.
6. If a catch-all space is defined, save the resulting routing.
7. If a routing has been saved, TeamPage creates a new entry on behalf of the user who sent the message and attempts to post it. If the entry cannot be posted -- which is usually due to permissions, but could have other causes, such as an expired TeamPage license -- or if no routing has been saved at an earlier step, the incoming message has been rejected: an email bounce message is sent to the sender. If the sender of the message could not be identified as a real TeamPage user account, no bounce message will be sent. The subject and body of all rejected messages are saved in the file server/dead.letter.
If you want to see these rules being applied, you can enable "mail" debugging on the Server Setup > Server Files page's Log Files > Debug tab, send messages to the server mailbox, and monitor the debug log file to see the resulting routing debug output. You will see information relating to the matches identified in each step in the process above.
