CS Dev Guide: Emailing in Community Server 2007
Back in September 2006 I wrote a CS Dev Guide post about emailing in Community Server 2.1. In Community Server 2007 emailing has changed a lot and now we can consider it as something completely new. I can say that Ken Robertson has done a great job on enhancing email features in Community Server 2007 and thank to his additions, now emailing is extendable and you can customize emailing features easily. In this post I want to talk about emailing in Community Server 2007 which is now known as MailRoom in APIs.
CommunityServer.MailGateway.MailRoom is responsible for emailing in Community Server 2007 (I ignore MailGateway as a commercial add-on here). There you can find an EmailJob which sends queued emails on a regular basis. Beside this, there are some classes that contain a list of methods to return template email texts to be sent.
For example, CommonEmails contains a list of common text templates for some scenarios like sending an email from one user to another via UserToUser method or notification email for password change for a user via UserPasswordChanged method.
There are also some classes specifically designed for emails that belong to specific applications. For example, WeblogEmails is a class that contains some methods for email text templates for weblog emails like WeblogFeedbackNotification which sends a notification email for feedbacks on a blog.
The most important and common class in this namespace is Emails which contains a collection of methods to work with emails. Some of these methods are some ready to go email templates for common scenarios (and most of them are available in CommonEmails class as well). But here there are some methods that need special attention:
- CanSend: This is a Boolean function to test if a user can send emails or not.
- FormatHtmlAsPlainText: Gets a string value as HTML and returns its plain text equivalent.
- FormatPlainTextAsHtml: Gets a string value as plain text and returns its HTML equivalent.
- GetTemplate: This method has two overloads to get an email type as string, a user and return an EmailTemplate object for that user and email type. Email type string value is something that you define for your email templates in their XML files.
- QueueMessage: This method has two overloads and it can either queue an Telligent.MailGateway.Common.Components.EmailTemplate or System.Net.Mail.MailMessage object.
As is obvious from above discussion, for sending emails you have two choices:
- Choose from a list of common email templates provided in Community Server and use some available methods for them to send your email.
- Create a Telligent.MailGateway.Common.Components.EmailTemplate or System.Net.Mail.MailMessage manually and queue it.
Knowing these principles, let me give three examples to clarify things.
First of all, let me use an email template to send an email after changing the password for current user to notify him or her about this change. Here I create an instance of CommonEmails class and use its UserPasswordChanged method to notify the user.
void ChangePassword()
{
CSContext context = CSContext.Current;
string newPass = "NewPass";
context.User.ChangePassword("OldPass", newPass);
CommonEmails emails = new CommonEmails();
emails.UserPasswordChanged(context.User, newPass);
}
In the second example, I create a MailMessage object and set its properties to send an email from current user to the admin user of the site then queue this email with Emails.QueueMessage method.
void SendEmailWithMailMessage()
{
CSContext context = CSContext.Current;
MailMessage message = new MailMessage(context.User.Email,
context.SiteSettings.AdminEmailAddress);
message.Subject = "Hey Admin!";
message.IsBodyHtml = false;
message.Body = "What are you doing?! :-D";
Emails.QueueMessage(message);
}
And in the last example, I use Telligent.MailGateway.Common.Components.EmailTemplate to send an email. This class is very similar to System.Net.Mail.MailMessage class but with some extra properties and methods. You create your email based on this class and use Emails.QueueMessage method to queue it. But here there is a point: you can insert some tokens in your email body in order to replace them with some values when you want to queue the email. To do this, you need to pass a list of
void SendEmailWithEmailTemplate()
{
CSContext context = CSContext.Current;
Telligent.MailGateway.Common.Components.EmailTemplate template =
new Telligent.MailGateway.Common.Components.EmailTemplate();
template.Subject = "Hello";
template.Body = "How are you? I'm [name]!";
template.From = new MailAddress(context.User.Email);
template.To.Add(new MailAddress(context.SiteSettings.AdminEmailAddress));
List<Telligent.MailGateway.Common.Components.EmailTextToken> tokens =
new List<Telligent.MailGateway.Common.Components.EmailTextToken>();
Telligent.MailGateway.Common.Components.EmailTextToken token =
new Telligent.MailGateway.Common.Components.EmailTextToken("name",
context.User.DisplayName);
Emails.QueueMessage(template, tokens);
}
Here at the end, I would like to point to something about the way that emails are stored in Community Server 2007. In this version, that traditional way of storing email fields in database columns is replaced with a new approach that lets an email to be extended and stored easily in the database. This new approach is nothing more than serializing the MailMessage object into XML format and storing this XML document in database.
[advertisement] Axosoft OnTime 2008 is four developer tools in one: bug tracking, project wiki, feature management, and help desk. It manages your development process so developers can focus on coding. Installed or Hosted – Free Single-user license -- Free 30-day team trial.
4 Comments : 09.08.07
Feedbacks
Can you post a sample SendEmailWithEmailTemplate with a body of HTML content?
When I call Emails.QueueMessage(template, tokens), I get the following exception (earlier stack trace removed for brevity).
I'm flipping on IsHtml and have tried different root tags in the template.Body...
System.Xml.XmlException was unhandled
Message="Root element is missing."
Source="System.Xml"
LineNumber=0
LinePosition=0
SourceUri=""
StackTrace:
at System.Xml.XmlTextReaderImpl.Throw(Exception e)
at System.Xml.XmlTextReaderImpl.ParseDocumentContent()
at System.Xml.XmlLoader.Load(XmlDocument doc, XmlReader reader, Boolean preserveWhitespace)
at System.Xml.XmlDocument.Load(XmlReader reader)
at System.Xml.XmlDocument.LoadXml(String xml)
at Telligent.MailGateway.Common.Components.EmailTemplate.ParseTemplate()
at CommunityServer.MailRoom.Components.Emails.QueueMessage(MailMessage message)
at CommunityServer.MailRoom.Components.Emails.QueueMessage(EmailTemplate message, List`1 tokens)
at ....
#1
Dave Burke
09.09.2007 @ 8:11 PM