Integrating into another web application

CONTENT

1. Summary

2. Interface aspect

3. User accounts database aspect

4. Integration object

4.1. Methods

5. Usage examples

5.1. Example 1

5.2. Example 2

5.3. Example 3

Summary

AfterLogic WebMail can be easily integrated into any existing ASP.NET application. There are two integration aspects:

interface - make WebMail interface a part of your ASP.NET application interface;

user accounts database - allow your application to pass credentials to WebMail to achieve bypassing WebMail's login screen and entering user's email account directly.

Interface aspect

You may need to make WebMail interface a part of your web site interface. For example, if your web site has several sections (e.g. "My Blog", "My Pictures", "My Mail") and a navigation menu which should always stay on the screen (no matter which section is currently selected), WebMail shouldn't overlap the navigation menu and shouldn't be opened in a separate window. To achieve this, you need to place WebMail into an IFRAME which is a part of your interface. Placing WebMail directly into your interface (e.g. into a DIV element) is not possible as it's complex AJAX application which relies to absolute coordinates and has its own system of exchanging XML packets with server. So, an IFRAME is the only way to get it working properly.

How to place WebMail into an IFRAME correctly? The following simple example demonstrates that:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" />
<html>
<head>
     <title>iframe test</title>
</head>
<body>
     <div style="background-color: #EEE; width: 900px;">Your navigation menu here</div><br />
     <iframe src="http://www.afterlogic.com/webmail-lite/default.aspx" style="width: 900px; height: 600px;"></iframe>
</body>

Here, you can see http://www.afterlogic.com/webmail-lite/default.aspx. It points to AfterLogic WebMail Lite ASP.NET live demo at our web site. You should change this URL to the one pointing to your WebMail installation.

User accounts database aspect

If your web site has its own sign in form where users should specify their e-mail (or just login) and password to log into their private area, it makes sense to use these credentials to log into their WebMail Lite accounts. Of course, it's inconvenient to type the same credentials again in WebMail sing-in form. Special integration API allows you to avoid this. It allows direct entering not only message list, but other WebMail screens like compose new message, calendar, etc.

To bypass WebMail sign-in screen and enter user's email account directly, it's necessary to pass some data that identify user in WebMail system. WebMail provides Integration object for this purpose.

Integration object

Usage of Integration object is simple:

1. Add a reference to WebMail.dll to your project (in Visual Studio 'Project->Add Reference...'). WebMail.dll is located in the bin subfolder of the root folder of your AfterLogic WebMail installation.

2. Import WebMail namespace:

using WebMail;

3. Create Integration object:

Integration integr = new Integration(@"C:\WebMail-Lite-Net\data", @"http://myserver/webmaillite/");

The first parameter is a physical path (not URL) to the WebMail data folder. The same path is specified in web.config file in the WebMail root folder. Relative paths like ../webmail_lite_data are supported too.

The second parameter is URL path to the WebMail root folder necessary for correct UserLoginByEmail method work. Please note, it's not a physical path like C:\inetpub\wwwroot\WebMail, but an URL like http://www.mydomain.com/webmail or relative URL like subparts/webmail.

4. Now, for instance, we need to log a user into WebMail bypassing standard sign-in screen. Let's call UserLoginByEmail method for this purpose:

integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.Mailbox);

"user@domain" - user's full e-mail address;

"user" - user's login (username). It may be either full e-mail address or just username without domain part, depends on your mail server configuration;

"password" - user's password. May be equal to null;

WMStartPage.Mailbox - enumeration member determining the screen the user will be redirected to after logging in.

For more various examples, see Usage Examples.

Methods

GetAccountById(id)	Gets Account object by id of user in the database (awm_accounts.id_acct), or null on error.
UserLoginByEmail(email, login, password, startPage, recipient)	Performs login and redirects the user into WebMail system. IMPORTANT: that user must already exist in WebMail Lite database, otherwise, logging in will fail, in this case, it's necessary to create the user first. email, login - required parameters. startPage - enumeration member determining the screen the user will be redirected to after logging in. password - may be equal to null. If null, password validation is not performed, i.e. means "any password", but not "empty password". recipient - e-mail address which will be put into To field. Is used in case of redirection to compose message screen (WMStartPage.NewMessage) only, in other cases should be null.
All these methods may throw WebMailException.

WMStartPage enumeration members

Determines the screen the user will be redirected to after logging in.

Value	Description
Mailbox	Message list screen.
NewMessage	Compose message screen.
Settings	User's settings screen.
Contacts	User's contacts screen (addressbook).

Usage examples

Example 1

On the ASP.NET page you want to launch WebMail from, add the lines similar to the following:

Integration integr = new Integration(@"C:\WebMail-Lite-Net\data", @"http://www.mydomain.com/WebMail-Lite-Net/");
try
{
    integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.NewMessage, "user1@domain");
}
catch (WebMailException ex)
{
    // handle exception
}

The code above will redirect to WebMail system and immediately open message compose screen with 'user1@domain' address in "To" field. Please note, the account you need to log into must already exist in WebMail Lite database.

Once UserLoginByEmail method called, there are two cases possible:

Specified email address was found in WebMail database. The user is redirected to Inbox of the email account. Email account properties are taken from the database (you can adjust them in Admin Panel).

Specified email address was NOT found in WebMail database or an error occurred. In such case WebMailException will be thrown.

Example 2

The above example assumes WebMail Lite and your application are deployed on the same physical machine. In other words, you can easily reference WebMail.dll on local filesystem as well as specify physical path to the WebMail data folder. What to do if you need to integrate them when they're running on two different machines? The steps below would allow you to achieve that.

Let's assume your application is deployed on machine A, WebMail on machine B. The following conditions should be met:

1. Both the machines must be in the same local network.

2. MS Access database cannot be used as it cannot be accessed from local network, it's required to use MS SQL Server or MySQL database.

3. Both A and B machines must be able to connect to the same database server.

4. If the database connection is configured (in Admin Panel / WebMail / Database Settings) through DSN, you should create the same DSN on both A and B machines. In case of database connection through Host, nothing additional should be done on machine A.

5. Integration object created by your application on machine A needs access to WebMail configuration file (\DATA\settings\settings.xml) which is located on machine B. There're two ways to pull it round:

a) share WebMail data folder on machine B and set the Integration object on that path.

b) duplicate \DATA\settings folder along with settings.xml on machine A.

a. The way with sharing WebMail data folder.

Let's look at pros and cons of this way:

+ a single instance of settings.xml file, you don't need to bother about synchronizing the second copy on machine A when the original is changed by AdminPanel on machine B;

- you need to share the data folder for network access and take some security measures.

The easiest way is to share the data folder for public access, but it's insecure as any user is able to get the contents of that folder. You should create a new domain user and share the WebMail data folder to it, read permission is enough. So, no security breach would appear. The below is a bit modified Example 1:

Powerup.LicenseKey = "Your license key here";   // Your AfterLogic WebMail Lite ASP.NET license key here
Impersonation imperson = new Impersonation();
imperson.LogonAs("network_user", "domain.local", "password");

Integration integr = new Integration(@"\\LOCAL-SERVER\WebMail-Lite-Net\data", @"http://www.mydomain.com/WebMail-Lite-Net/");

try
{
   integr.UserLoginByEmail(@"user@domain", "user", "password", WMStartPage.NewMessage, "user1@domain");
}
catch (WebMailException ex)
{
  // handle exception
}
finally
{
  imperson.Logoff();
}

The trick is in the first three lines and the finally block. Your ASP.NET application is running under a local system account (local for machine A, usually, it's NETWORK SERVICE), but that local account is not allowed to access the network path you shared WebMail Lite data folder at. So, your application has to impersonate the domain user you've shared the data folder to.

Arguments of LogonAs method:

"network_user" - name of domain user account you shared the data folder to;

"domain.local" - name of the domain the user account belongs to;

"password" - password of the domain user account.

Also, you should add reference to MailBee.NET.dll to your project and import MailBee.Security namespace.

b. The way with duplicating WebMail settings folder.

Pros and cons:

+ nothing needs to be shared, no additional security measures needed;

- you need to synchronize the copy of settings.xml file on machine A with the one on machine B when AdminPanel updates it (when you change settings in its interface).

If you chose this way, you should copy the \DATA\settings folder (with contents) from machine B to A and set integration script on that path as in the samples above.

Example 3

Now, let's take advantage of both the integration aspects. First, please create test-iframe.aspx/test-iframe.aspx.cs file and copy/paste the code from Example 1 there, then modify the example to get it working in your environment. It's assumed that you placed that file into the web folder of your .NET application. Now, just add the following line to one of your web pages:

<iframe src="test-iframe.aspx" style="width: 900px; height: 600px;"></iframe>

As you can see, it refers to the file with the integration script you created previously. Both test-iframe.aspx and the page you placed the IFRAME to are in the same folder.

Now, you may wonder how to pass authentication data from your ASP.NET application to UserLoginByEmail method called in test-iframe.aspx. Don't pass that data through GET method (in URL after ? char) for security reasons, but use server-side ASP.NET sessions instead. Example:

A part of default.aspx file:

<%
// Store credentials in session
Session["email"] = "john_doe@mydomain.com";
Session["login"] = "john_doe";
Session["password"] = "mypassword";
%>
<iframe src="test-iframe.aspx" style="width: 900px; height: 600px;"></iframe>

A part of test-iframe.aspx.cs file:

Integration integr = new Integration(@"C:\WebMail-Lite-Net\data", @"http://www.mydomain.com/WebMail-Lite-Net/");

try
{
  integr.UserLoginByEmail(Session["email"], Session["login"], Session["password"], WMStartPage.Mailbox, null);
}
catch (WebMailException ex)
{
  Response.Write("Error: failed to log into the account. Reason: " + ex.Message);
}

Lite version of AfterLogic WebMail doesn't provide any other integration features besides bypassing login screen described above. However, you may take a look at Pro version which provides advanced integration capabilities - integration API.