How to integrate WebMail into another system

WebMail can be easily integrated into any existing system.

To bypass WebMail's login screen and enter user's email account directly, it is required to set up 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

include('integr.php');

2.  Create "CIntegration" object:

$Integr = new CIntegration($webmailrootpath = null);
$webmailrootpath - 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.

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

$Integr->UserLoginByEmail($email, $login, $startPage, $password);
$password - optional parameter.
$startPage - a constant determining the screen the user will be redirected to after logging in.

See also Usage Examples for details on user's account upates in WebMail system.


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 specified 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 user into WebMail system.

$email, $login - required parameters.
$startPage - a constant determining the screen the user will be redirected to after logging in.
$password - optional parameter
$toEmail - optional parameter
GetErrorString() Gets the last error description.

$startPage constants (determine 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)

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 similar to the following:

<?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 will redirect to WebMail system and immediately open "login@domain.com" mailbox.

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 (specified through "WebMail Settings" in "Administration Panel").

2. Specified email address was NOT found in WebMail database. In such case the method returns false.

Example 2:
<?php
include('integr.php');

$Integr = new CIntegration();

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

This sample creates a user in WebMail database and displays error description on error.

Example 3:
<?php
include('integr.php');

$Integr = new CIntegration();

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

echo $account->Email;
?>

This sample gets all user's data (as Account object) from WebMail database.


If you have any questions don't hesitate to email to support@afterlogic.com
Or visit our support web page at http://www.afterlogic.com/support
or web forum at http://www.afterlogic.com/forum