Mail Gateway

The Telligent Evolution Platform uses Mail Gateway for its email functionality. Mail Gateway can be broken down into two components: Incoming and outgoing. The incoming component consists of the Mail Gateway service that is installed on the machine. It receives emails into it (via POP3, IMAP, or from a directory) and converts them into posts on the site. The outgoing component sends emails out to users, notifying them of activity on the site. This document covers the outgoing component of Mail Gateway.

Services and utilities

These services are used to accomplish the various tasks required by Mail Gateway to send email notifications. Almost all of the services have a matching interface and can be extended/replaced via the module entries. It is not advisable to do this with any of the services unless you know what you're doing.

EmailBuilder

This service is responsible for rendering the different parts of the email (subject and body) through the Velocity engine and building the resulting email string. It also inserts all the headers used in the email. This service is used internally by the EmailSendingService.

EmailChecks

This service encapsulates a variety of checks for email. All email providers respect these settings when sending users email.  Any new providers must do so, also. The service offers the following checks:

EmailContext

This object stores context data for the email being generated. This data includes who the email is from, what user(s) it is direct to, email headers, and objects considered in context. These last objects are used to pass specific data from the email code to the template to be used in rendering.  Only one of any given type can be added to the context (i.e., a User and a Forum Post can both be added to the context, but two different User objects cannot). If more than one of a particular type of object needs to be added to the context, a wrapper object should be used instead.

Note: EmailContext should not be created using new, use EmailContextService.Create() instead.

EmailContextService

This service is used to create, retrieve, and clear the EmailContext. When creating an EmailContext, context items are passed in as parameters. It is still possible to add further items via EmailContext.AddContextItem(object). Once created, the EmailContext is stored in the CSContext Items with the name "EmailContext" so it can be retrieved when rendering the email. The EmailContext is automatically cleared once the email is queued in the EmailSendingService.

EmailDigestStrategy

This class defines the start and end dates to use when retrieving activity messages used by the email digest feature. For daily digests, it returns from 12:00am of the previous day to 11:59:59pm of the previous day. For weekly digests, it returns from 12:00am 7 days prior to 11:59:59pm of the previous day.

EmailQueuingService

This service is responsible for rendering an email template and queuing it to be sent by the EmailJob. It delegates rendering the template to EmailBuilder. This service is the only way email should be queued into the EmailJob.

EmailTemplateExtensionService

This service is responsible for creating the Velocity context used when rendering templates and injecting all plugins that extend the IEmailTemplateExtension interface into the context.

EmailTemplateLoader

This service loads template files into the system for the EmailTemplateService. It looks in "/Web/Languages/<supported_language>/emails" (where <supported_language> is any language declared in /Web/Languages/languages.xml) for all xml files and attempts to load them as an email template. For any templates that fail to load, an exception is logged and the file is skipped.

EmailTemplateSerializer

This service is responsible for deserializing email template .xml files into EmailTemplate objects. It will log an EmailTemplateParseError exception for any templates that it cannot properly deserialize.

EmailTemplateService

This service loads and stores all EmailTemplates. Email providers will use this service to retrieve the desired email template, optionally specifying the language. If no language is provided or the language is no supported, the default language will be used. An EmailTemplateNotFound exception will be thrown if no email template is found.

EmailTemplateUtility

This class is responsible for a wide variety of email rendering related tasks. It formats the To and From fields, renders content to either html or plain text, despite its original format, and parsing strings into various objects, among others. It is available in code and is also exposed in the email templates using the $email_utility token.

If, during the process of rendering a email, it is determined the email should not be sent, the template can call $email_utility.CancelEmail() to halt email rendering

Data flow for sending emails

The following chart shows how emails are generated and sent. Any custom emails will follow a similar pattern.

Email providers

Email providers encapsulate the email sending process into a single method call. They take in the necessary information and trigger the appropriate email to be sent. Below are the various methods defined for each of the providers, the template(s) they use to send email, and a description of what they do.

Common

Blogs

Forums

Groups

Messages

Messages

Wikis

Related information

• Extending email via IEmailTemplateExtension