Doc86: Sending Email to TeamPage

Title: Sending Email to TeamPage

TeamPage can read email from a Pop3(s) or IMAP(s) mailbox and publish it to the server. This works for mailing in new entries as well as for replying to email notifications from TeamPage. Mailboxes can be configured per space or at the server level, although the server level method works better for most purposes.

When sending mail to a server mailbox, you can use simple markup for targeting spaces, adding entries as comments, specifying entry type (Task vs. Article vs. Status, and so on), assigning a task to a person and associating a task or article to a project.

A server-level mailbox is ideal for cases where you use just one email address to send information to your TeamPage server, or reply to email notifications that TeamPage sends to you. Your reply is automatically routed back to the right space as a new article or comment. You can also choose a space, tag, entry type and more using the Subject line of email you send to TeamPage.

Per-space mailboxes should be used only when email to a given address must only be logged to a specific space, with no possibility that the email's content be posted to a different space, regardless of any subject line commands.

Server Level TeamPage Mailbox—Subject Line Commands

TeamPage can be configured to read one common mailbox for the whole server. TeamPage servers hosted by Traction Software all have server-level mailboxes. If your TeamPage server has been configured to read a server mailbox, and you have Author by Email permission in at least one space, you will see the server mailbox's address in the right column of certain all spaces pages, such as the front page (All Spaces Dashboard).

TeamPage server administrators can add custom rules for routing messages read from the server mailbox, but users typically target a specific space by including a simple command like this in the subject of an email addressed to the server mailbox:

@spacename

For example, to send a message to the Support space, we could include @Support in our subject:

(In this example, the "bug" tag is also being applied to the new article using standard TeamPage tagging syntax.)

It doesn't matter where the text "@Support" appears in the subject. As long as "Support" matches the name of an active space, the message will be routed to the Support space. In this example, we see that TeamPage read this message and created a new article in the Support space:

TeamPage removed "@Support" from the text taken from the subject that was used to create the article's title, but not from the raw headers captured from the original message. The raw headers are stored along with every article created from an email message.

Other Subject Directives

There are other kinds of instructions you can give to TeamPage in the subject of your message about how to treat your new post.

Commenting

You can also make a new comment on an existing entry -- or even a particular paragraph -- using the similar syntax, also in the message subject:

@TractionID

(The TractionID is the unique identifier for any article or paragraph, composed of the space's name, the entry's numeric ID and, optionally, the paragraph's numeric ID.)

If you're sending your message to the server mailbox, you can use this in conjunction with the @spacename syntax to post your comment in a space other than the moderation space for the article you're commenting on, as long as you have permission to do so. To post a comment on the paragraph with the ID 03 in the entry MarketResearch3, but post your comment in the Internal space, your message subject could look like this:

In this example, we see that TeamPage read this message and created a new comment on paragraph 03 in MarketResearch3:

To make a comment on the entire article instead of paragraph 03, the subject could include "@MarketResearch3", leaving out the ".03". If "@Internal" had been left out of the subject, the resulting comment would be posted to the MarketResearch space's moderation space.

This feature is designed to work in conjunction with TeamPage's email notification capabilities: if you receive an email notification for a newly created article or comment and you have permission to comment on that article, the subject of the message will already contain the appropriate text to make your reply a new comment on the article or comment. All you have to do is click the "Reply" button in your email software. (TeamPage will even strip out the quoted text included below your reply from the message body before using it to create your comment.)

Posting Special Types of Entries

You can post special types of entries, such as status updates, tasks, and even projects and milestones, by using the special entry type syntax at the beginning of your subject line:

entrytype:

When you use this kind of prefix in your message subject, you can still use a @spacename directive to route your message to the appropriate space (if you're sending to the server mailbox). But the meanings of any @TractionID directives in your message subject may change, depending upon what type of entry you're posting. Here are the types that are supported in TeamPage out of the box, and what Traction ID directives mean for each one.

status

Example:

This message, sent to the server mailbox, creates a new status update in the Team space, which is the default space for posting status updates (notice we left out the @spacename directive):

Since the subject is used as the entry title, and status updates entries' titles aren't usually displayed, you don't really need to type anything other than "status:" in your subject line to post a status update. (Indeed, if you do, it will be stored as the status update entry's title, but it won't appear in most places where the status update is displayed.) The Traction ID directive in the message subject for a status update still means the same thing: make the status update a reply to (comment on) an existing entry or paragraph.

task

Example:

This message, sent to the server mailbox, creates a new task.

The Traction ID directives in the message subject can be used for different purposes:

To associate the task with a project;
to associate the task with a milestone;
and to make it "task" existing content by associating the task with an entry or paragraph.

In this case, the task was associated with the project Team73 and the milestone Team74, and tasked the existing entry Basic71:

The ID of the project or milestone appears as part of the tab/window title when you are viewing a single project or milestone:

These ID directives for associating a task can be included in any order, and are all optional.

You can also include user directives to assign the task to a user. User directives may use this syntax with the user's email address, literally including the < > characters as brackets:

@<email address or user name>

In this example, the user account that has the email address bob@example.com will become an assignee of the new task being posted in the Team space:

task: Buy a New Laser Printer @<bob@example.com> @Team

This this second example, the user account corresponding to the user name karen.johnson and the user account that has the email address jack@example.com will both become assignees of the new task. Also note that the directive "@Team57" could be any of the supported ID directives described above, depending upon what kind of entry Team57 is:

task: Restock Supply Room @Team57 @Team @<karen.johnson> @<jack@example.com>

The user directives for assigning the task may be included in the message subject in any order, and may use either supported format.

You can use the special user directive, with no address or username between the angle brackets:

@<>

to refer to yourself. This makes it easy to assign a new task to yourself with a message subject like this:

task: Clean up My Desk @Team @<>

Example:

This message, sent to the server mailbox, would post a new article related to the project Team73. It will be displayed on the project's Related Articles tab and the Related Articles of its Dashboard:

Notice that no space name directive was included in the message subject. By default, related articles posted from a message read from the server mailbox are routed to the target entry's space.

milestone

Example:

This message, sent to the server mailbox, would create a new mliestone associated with the project Team73:

As with the related article example above, notice that no space name directive was included in the message subject. By default, milestones posted from a message read from the server mailbox are routed to the associated project's space.

project

Example:

This message, sent to the server mailbox, would create a new project in the Team space:

Notes on Message Routing

No matter what instructions you put in the subject line of your message, if you address it to a dedicated per space mailbox, your TeamPage server will always attempt to post it to that space.

If you list more than one subject space or common mailbox address in an email message, only one copy of email message will be posted to the first space or address that matches the message routing rules.

Please see Common TeamPage Server Mailbox Configuration for complete details on how messages read from the server mailbox are routed.

Dedicated per Space Mailboxes

Alternatively and additionally, individual TeamPage spaces can be configured to read a dedicated mailbox. This is useful for cases where a space is used to collect messages sent to a standard email address you want to publish widely. For example, the email address TeamPageSuggestions@your-company.com might collect TeamPage-related suggestions from your team and log them to a Space that's configured to read that mailbox (only one Space should be configured to read the same dedicated mailbox).

Each per-space mailbox must have a corresponding email account with POP or IMAP mailbox access. Additionally, a TeamPage space administrator needs to configure each space to read its individual mailbox.

Users who have Author by Email permission can create new articles in that space by sending email to that mailbox. If your user account has Author by Email permission in a particular space, you can find out the email address of the space in the side column of a page focused on that space, such as the Space Dashboard:

Limitations on Space Mailboxes

• Space routing commands like @spacename do not work in space mailboxes

• Entry type selectors, like task:, also do not work in space mailboxes

Subject, Body and Attachments

Whether addressed to a space mailbox or the server mailbox, email messages send to TeamPage can be just like any other email message.

The subject of the message is used to create the title of the article; and the body of the message is used to create the article's content. Attachments to the message are stored as attachments to the new article, and inline images still appear inline in the article's content where they appeared in the message's body.

The headers from the original email message are captured and stored with the article. By default, only the most important email headers -- the From, To and Date headers -- are displayed at the end of the article. The resulting article can be edited to change how much email header information should be displayed, or even to turn off their display altogether, using the "Headers" control that appears in the editor. The default "volume" for the headers may be changed by space administrators.

Important Tips

1. Write a good first paragraph! The first paragraph shows up in the email digest and in brief content views.

2. If you're going to send messages to a TeamPage space mailbox, be sure the email address you're using (the address that appears in the From header) is associated with your account. This is how TeamPage will know to create a new article attributed to you. Otherwise, TeamPage will either reject the message (you may receive a bounce message), or create a new article attributed to the built-in Visitor account instead of your account (if Visitor has Author by Email permission in the space).

Note that in the examples above, you can see that the message came from Dave Shepperton. The messages were sent to an email address, teampage@shepperton.us. Since the email address shep@tractionserver.com is associated with an active user account that has Author by Email permission in the MarketResearch and Internal space, when the resulting articles are viewed, TeamPage indicates that they were Created by Dave Shepperton. If the email address had not been registered with a known user account, and the built-in Visitor account had permission to create those posts, they would have been created as Visitor instead, and TeamPage would have indicated that they were Created by Visitor.

Attachments:

side-column-mailbox-info.png
support-space-msg.png
support-space-entry.png
marketresearch-comment-msg.png
marketresearch-comment-entry.png
simple-status-update.png
status-update.png
task-message.png
task-entry.png
project-window-title.png
related-message.png
related-entry-list.png
milestone-message.png
milestone-entry.png
project-message.png
project-entry.png

referenced by (6)

Doc1443: Inviting People to TeamPage Customer3427: TeamPage 5.2.0.2 Doc1107: Common TeamPage Server Mailbox Configuration Doc357: Traction User Guide Doc192: Overview of the Space ACL Editor Doc5: Add New Article

Article: Doc86 (permalink)
Categories: :Doc:R52
Date: March 22, 2008; 3:56:46 PM Eastern Daylight Time

Author Name: Documentation Importer
Author ID: importer