WebMail Pro documentation

Embedding WebMail into your web application via IFRAME

Introduction

You may need to make WebMail Pro 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 interface shouldn't overlap the navigation menu and shouldn't be opened in a separate window.

To achieve this, you need to place WebMail Pro interface into an IFRAME which is a part of your interface. Placing it directly into your interface (e.g. into a DIV element) is not possible as it's a complex web application, so an IFRAME is the only way to get it working properly.

Note that it's possible to disallow placing WebMail Pro interface into IFRAME, see Preventing clickjacking attacks with X-Frame-Options header documentation page for details.

Simple embedding into your interface

The following example demonstrates how to place WebMail Pro interface into an IFRAME:

<!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: 1000px;">Your navigation menu here</div><br />
        <iframe src="https://webmail.afterlogic.com/" style="width: 1000px; height: 640px;"></iframe>
    </body>
</html>

Here, you can see https://webmail.afterlogic.com/ URL mentioned. It points to AfterLogic WebMail Pro PHP live demo at our web site. You should change this URL to the one pointing to your product installation.

Note that in version 7, IFRAME height and width should be 640 x 800 at least, to avoid getting scrollbars.

Embedding into your interface along with passing authentication data

Now let's use visual integration along with passing authentication data to WebMail Pro which is described here. First, please create test-iframe.php file and copy/paste the code from that page, then modify the example to get it working in your environment. It's assumed that you placed that file into main directory of your WebMail Pro installation. The code will be slightly modified (see below).

Now, just add the following line to one of your PHP pages:

<iframe src="/webmail/test-iframe.php" style="width: 1000px; height: 640px;"></iframe>

Now, you may wonder how to pass authentication data from your PHP application to Login method called in test-iframe.php. We won't pass those data through POST method, server-side PHP sessions are used instead. Example:

index.php file:

<?php
session_start();
// Store credentials in session
$_SESSION['email'] = 'john_doe@mydomain.com';
$_SESSION['password'] = 'mypassword';
?>
<iframe src="/webmail/test-iframe.php" style="width: 1000px; height: 640px;"></iframe>

webmail/test-iframe.php file:

<?php
session_start();
// Example of logging into user account using email and
// password for incorporating into another web application
// utilizing WebMail Pro API
include __DIR__.'./system/autoload.php';
\Aurora\System\Api::Init();
// data for logging into account
$sUserLogin =  $_SESSION['email'];
$sUserPassword = $_SESSION['password'];
$aData = \Aurora\System\Api::GetModuleDecorator('Core')->Login($sUserLogin, $sUserPassword);
if (isset($aData['AuthToken']))
{ 
    $sAuthToken = $aData['AuthToken'];
    setcookie('AuthToken', $sAuthToken, time()+3600, "/");
    // redirecting to WebMail Pro main page    
    \Aurora\System\Api::Location('/');
}
exit();

Cross-domain cookies in IFrame

It appears that Google Chrome and other Chromium-based web browsers blocks cookies within cross-domain IFrame unless they have SameSite attribute explicitly disabled. We plan to add a configuration option for that, meantime you can correct the behavior by modifying statis/js/app.js file. Locate the following code in it:

return (document.cookie = [
    encode(key), '=', stringifyCookieValue(value),
    options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
    options.path    ? '; path=' + options.path : '',
    options.domain  ? '; domain=' + options.domain : '',
    options.secure  ? '; secure' : ''
].join(''));

and adjust it as follows:

var issecure = window.location.protocol=="https:";
return (document.cookie = [
    encode(key), '=', stringifyCookieValue(value),
    options.expires ? '; expires=' + options.expires.toUTCString() : '', // use expires attribute, max-age is not supported by IE
    options.path    ? '; path=' + options.path : '',
    options.domain  ? '; domain=' + options.domain : '',
    issecure ? '; secure; SameSite=None' : ''
].join(''));

You'll need to set "UseAppMinJs" to false in data/settings/config.json file for this to work (so that non-minified JavaScript is loaded instead of minified one), and clear browser cache to apply changes.

NB: Currently, it seems setting SameSite=None will only work if Secure attribute is set - which in turn only happens if the installation is accessed over https. To make this work, you need to have both the external website and the WebMail Pro installation accessed over https rather than http.

Advanced integration methods

The above integration approach requires both your application and WebMail Pro installation to be on the same server and in the same domain. If the two run on different domains, you can try Single Sign-On approach.

And if your application and WebMail Pro installation are on two different systems, you can sending login credentials via POST.