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

Here, you can see http://www.afterlogic.com/webmail-pro-php/index.php. It points to AfterLogic WebMail Pro PHP 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 Pro 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 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.
GetAccountByMailLogin($email, $login) Gets Account object by e-mail address and login or null on error.

$email, $login - required parameters.
CreateUser($email, $login, $password) Creates a user in WebMail database.

$email, $login, $password - required parameters
Default values are assigned to all other settings like POP3/IMAP4/SMTP servers, etc.
CreateUserFromAccount(&$account) Creates a user in WebMail database with settings defined in Account object.
UserExists($email, $login) Checks if the user exists in WebMail database.

$email, $login - required parameters.

Returns true if the user exists, false if doesn't.
UserLoginByEmail($email, $login, $startPage, $password, $toEmail) Performs login and redirects the user into WebMail system. IMPORTANT: that user must already exist in WebMail Pro database, otherwise, logging in will fail, in this case, it's necessary to create the user first. See this example for more details.

$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).
START_PAGE_IS_CALENDAR User's calendar screen.

Account object (represents a user account in WebMail, contains all user account settings and is used for more flexible user accounts management)

Value Description
Id (int) Account unique identifier (awm_accounts.acct_id).
Email (string) Email address.
DefaultAccount (bool) Indicates if the account is default (primary), i.e. can be used for logging into WebMail.
MailProtocol (int) Protocol of the account.

Possible values:
MAILPROTOCOL_POP3 - POP3 protocol.
MAILPROTOCOL_IMAP4 - IMAP4 protocol.
MAILPROTOCOL_WMSERVER - communicating with local mail server.
MailIncHost (string) Incoming mail server address (e.g. mail.domain.com).
MailIncPort (int) Incoming mail server port number (110 for POP3, 143 for IMAP4).
MailIncLogin (string) Login for incoming mail server.
MailIncPassword (string) Password for incoming mail server.
MailOutHost (string) Outgoing mail server address (e.g. mail.domain.com).
MailOutPort (int) Outgoing mail server port number (25 for SMTP).
MailOutLogin (string) Login for outgoing mail server.
MailOutPassword (string) Password for outgoing mail server.
FriendlyName (string) A name to be added to e-mail address in From field of outgoing messages.
GetMailAtLogin (bool) Indicates if message receiving should be performed automatically after logging into WebMail under this account.

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 Pro 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

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.

<?php
include('integr.php');

$Integr = new CIntegration();

if(!$Integr->CreateUser('login@domain.com', 'login', 'password'))
{
   echo $Integr->GetErrorString();
}
?>

This sample demonstrates simple creating user in WebMail database. On error, it displays error description.

Example 3

On the PHP page you want to launch WebMail from, add the lines like the ones below. As integr.php is included not from the current folder and CIntegration instance is created with the argument ($webmailrootpath), it's assumed that the page you're adding this code to is placed outside of WebMail root folder, most probably, in your PHP application folder. Don't forget to change C:\Projects\webmail\integr.php to correct path to integr.php and http://www.mydomain.com/webmail/ to correct URL pointing to the root folder of your WebMail installation.

<?php
include('C:\Projects\webmail\integr.php');

$Integr = new CIntegration('http://www.mydomain.com/webmail/');

$account = $Integr->GetAccountByMailLogin('login@domain.com', 'login');

echo $account->Email;
?>

Example 4

On the PHP page you want to launch WebMail from, add the lines like the ones below. As integr.php is included not from the current folder and CIntegration instance is created with the argument ($webmailrootpath), it's assumed that the page you're adding this code to is placed outside of WebMail root folder, most probably, in your PHP application folder. Don't forget to change C:\Projects\webmail\integr.php to correct path to integr.php and http://www.mydomain.com/webmail/ to correct URL pointing to the root folder of your WebMail installation.

<?php
include('C:\Projects\webmail\integr.php');

$Integr = new CIntegration('http://www.mydomain.com/webmail/');

$email = 'john_doe@mydomain.com';
$login = 'john_doe';
$password = 'mypassword';

$pop3 = 'pop.mydomain.com';
$smtp = 'smtp.mydomain.com'

if (!$Integr->UserLoginByEmail($email, $login, START_PAGE_IS_MAILBOX, $password))
{
    // Failed to log in, will try creating such account
    $acct = new Account();

    $acct->Email = $email;
    $acct->MailIncLogin = $login;
    $acct->MailIncHost = $pop3;
    $acct->MailIncPassword = $password;
    $acct->MailIncPort = 110;
    $acct->MailOutLogin = $login;
    $acct->MailOutHost = $smtp;
    $acct->MailOutPassword = $password;
    $acct->MailOutPort = 25;
    $acct->MailProtocol = MAILPROTOCOL_POP3;
    $acct->MailOutAuthentication = true;

    if ($Integr->CreateUserFromAccount($acct))
    {
        if (!$Integr->UserLoginByEmail($email, $login, START_PAGE_IS_MAILBOX, $password))
        {
            echo 'Error: the account has been created, but failed to log in though. Reason: ' . $Integr->GetErrorString();
        }
        else
        {
            echo 'Error: failed to log into the account. Reason: ' . $Integr->GetErrorString();
        }
    }
    else
    {
        echo 'Error: failed to create the account. Reason: ' . $Integr->GetErrorString();
    }
}
?>

This universal sample can be used in most cases. First, it tries to log user into his account. If the account doesn't exist, it tries to create it (with extended settings set). On success, it tries to log into the account just created. On any error, it displays error details.

IMPORTANT NOTE: The main difference between this example and Example 1 is that Example 1 allows logging into accounts which already exist in WebMail database, while this example creates new accounts in the database if they don't exist there. Sometimes, it's necessary to log into existing accounts only and you should refer to Example 1 in such case.

Example 5

Example 4 creates user with extended settings set, i.e. it calls CreateUserFromAccount method. This is necessary when you need to explicitly specify mail server settings (like in this sample, to create user in a domain not listed in Admin Panel) or any other settings. If you need to create an account with default settings specified in Admin Panel, you may simplify this sample as follows:

<?php
include('C:\Projects\webmail\integr.php');

$Integr = new CIntegration('http://www.mydomain.com/webmail/');

$email = 'john_doe@mydomain.com';
$login = 'john_doe';
$password = 'mypassword';

if (!$Integr->UserLoginByEmail($email, $login, START_PAGE_IS_MAILBOX, $password))
{
    // Failed to log in, will try creating such account
    if ($Integr->CreateUser($email, $login, $password))
    {
        if (!$Integr->UserLoginByEmail($email, $login, START_PAGE_IS_MAILBOX, $password))
        {
            echo 'Error: the account has been created, but failed to log in though. Reason: ' . $Integr->GetErrorString();
        }
        else
        {
            echo 'Error: failed to log into the account. Reason: ' . $Integr->GetErrorString();
        }
    }
    else
    {
        echo 'Error: failed to create the account. Reason: ' . $Integr->GetErrorString();
    }
}
?>

Example 6

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: