Integrating into another web application

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

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/" style="width: 900px; height: 600px;"></iframe>
    </body>
</html>

Here, you can see http://www.afterlogic.com/webmail-lite/. It points to AfterLogic WebMail Lite 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.

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 CIntegration object for this purpose.

Usage of CIntegration object is simple:

  1. Include integr.php file which is located in the root folder of your AfterLogic WebMail installation:

    include('integr.php');

    If the file you're adding this code to is outside of WebMail root folder, you should specify the appropriate path to integr.php.

  2. Create "CIntegration" object:

    $Integr = new CIntegration($webmailrootpath = null);

    $webmailrootpath - URL path to the WebMail root folder necessary for correct UserLoginByEmail method work. If the script calling UserLoginByEmail method is located in the WebMail root folder, or UserLoginByEmail method is not called, you may omit passing this parameter. Please note, it's not a physical path like C:\inetpub\wwwroot\WebMail or /var/www/html/webmail, but an URL like http://www.mydomain.com/webmail or relative URL like subparts/webmail.

  3. 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($email, $login, $startPage, $password);

    $email - user's full e-mail address;
    $login - 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. Optional parameter;
    $startPage - a constant 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, $startPage, $password, $toEmail) 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 - a constant determining the screen the user will be redirected to after logging in.
$password - optional parameter. If omitted or null, password validation is not performed, i.e. means "any password", but not "empty password".
$toEmail - optional parameter. Specifies e-mail address automatically set in To field in WebMail compose message screen in case if $startPage = START_PAGE_IS_NEW_MESSAGE
GetErrorString() Gets the last error description.

$startPage constants (determines the screen the user will be redirected to after logging in)

Value Description
START_PAGE_IS_MAILBOX Message list screen.
START_PAGE_IS_NEW_MESSAGE Compose message screen.
START_PAGE_IS_SETTINGS User's settings screen.
START_PAGE_IS_CONTACTS User's contacts screen (addressbook).

Usage examples:

Example 1

On the PHP page you want to launch WebMail from, add the lines like the ones below. As integr.php is included from the current folder and CIntegration instance is created without the optional argument ($webmailrootpath), it's assumed that the page you're adding this code to is placed into WebMail root folder. Also, the account you need to log into must already exist in WebMail Lite database.

<?php
include('integr.php');
$Integr = new CIntegration();

$mail = 'login@domain.com';
$login = 'login';
$pass = 'password';

$Integr->UserLoginByEmail($mail, $login, START_PAGE_IS_MAILBOX, $pass);
?>

The code above redirects to WebMail and immediately opens "login@domain.com" account.

Once UserLoginByEmail method called, there are two cases possible:

  1. 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).
  2. Specified email address was NOT found in WebMail database. In such case the method returns false.

Example 2

Now, let's take advantage of both the integration aspects. First, please create test-iframe.php file and copy/paste the code from Example 4 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 PHP application. Now, just add the following line to one of your PHP pages:

<iframe src="test-iframe.php" 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.php and the page you placed the iframe to are in the same folder.

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

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.