Creating domains, logging accounts in, deleting domains and accounts via API (WebMail Pro 6 PHP)

From AfterLogic Wiki

Introduction

If you have some existing web application, you might want to integrate WebMail Pro into it. It is possible to send authentication data from your application into WebMail Pro bypassing its login screen. You can also add/remove domains, delete user accounts and perform other actions with a few lines of PHP code.

In order to make use of WebMail Pro API, you'll need to load the API library and make sure CApi class can be used:

<?php
defined('WM_ROOTPATH') || define('WM_ROOTPATH', (dirname(__FILE__).'/../'));
include_once WM_ROOTPATH.'libraries/afterlogic/api.php';

WM_ROOTPATH constant should hold a filesystem path pointing to root WebMail Pro directory. In the above code, it is assumed that the integration code itself is located in subdirectory of root WebMail Pro directory. Once the library is loaded, we should check if it's ready for use:

if (class_exists('CApi') && CApi::IsValid())
{

If the above check is successful, we can start using API. It provides a number of managers, and if we need to work with domains in our code, 'domains' manager should be used, 'users' for handling user accounts, 'webmail' for basic webmail-related operations like logging in etc.

  $oApiDomainsManager = CApi::Manager('domains');

With the manager object instantiated, its class will be used then:

  $sDomainToDelete = 'domain.com';
  if ($oApiDomainsManager->DeleteDomainByName($sDomainToDelete))
  {

Below, you'll find a number of detailed examples which describe using WebMail Pro API.

Logging in programmatically

Method LoginToAccount

Logs user into specified email account. In case if the account was not created in WebMail yet but user can log into it, account will be created.

Parameters:

Returns CAccount object on success, false on error. Error message can be retrieved using GetLastErrorMessage method (see the example below).

Let's assume that you'd like to make WebMail Pro a solid part of your web site. Typical scenario is that you have a database table with user accounts stored there, and each user has email address and password associated with the account. For the sake of simplicity, we'll show how this works for simple HTML form used to deliver information about login and password:

<form action="int.php" method="POST">
E-mail: <input type="text" name="email"><br>
Password: <input type="password" name="password"><br>
<input type="submit" value="Enter"></form>

As you can see, the form is pointing to some int.php file, that's not a part of WebMail Pro itself. Below, we're going to create that file. We assume both the HTML file containing the form and int.php file are located in WebMail Pro subdirectory called, say, integration.

<?php
// Example of logging into WebMail account using email and password for incorporating into another web application
 
// determining main directory
defined('WM_ROOTPATH') || define('WM_ROOTPATH', (dirname(__FILE__).'/../'));
 
// utilizing WebMail Pro API
include_once WM_ROOTPATH.'libraries/afterlogic/api.php';
if (class_exists('CApi') && CApi::IsValid())
{
  // data for logging into account
  $sEmail = $_POST['email'];
  $sPassword = $_POST['password'];
 
  // Getting required API class
  $oApiWebMailManager = CApi::Manager('webmail');
 
  // attempting to obtain object for account we're trying to log into
  $oAccount = $oApiWebMailManager->LoginToAccount($sEmail, $sPassword);
  if ($oAccount)
  {
    // populating session data from the account
    $oAccount->FillSession();
 
    // redirecting to WebMail
    $oApiWebMailManager->JumpToWebMail('../webmail.php?check=1');
  }
  else
  {
    // login error
    echo $oApiWebMailManager->GetLastErrorMessage();
  }
}
else
{
  echo 'WebMail API not allowed';
}

The first thing to be done is to define WM_ROOTPATH constant which will hold the filesystem path to main WebMail Pro directory. If this code is not placed to WebMail Pro subdirectory, you'll need to adjust a value of this constant.

Once the API class is loaded, we retrieve email and password sent using HTML form, then we use those data to log into WebMail Pro.

To summarize: you'll need to send data to the integration code based on the above example, and in case if logging in is successful, WebMail Pro interface will be loaded, otherwise error message is displayed.

This operation is performed according to exactly the same model as we use in WebMail Pro login screen: if user account already exists, and the password is correct, user will be logged in. Otherwise, domain part of the email address will be checked against the list of domains, and WebMail Pro will try to access the email account. If that's successful, user account will be added to WebMail Pro database, and user will log in of course.

You can find an example of visual integration with your web application here.

Adding a domain

Method CreateDomain

Adds a domain into WebMail Pro database. Accepts full range of incoming/outgoing server connection parameters.

Parameters:

Returns true on success and false on error. Error message can be retrieved using GetLastErrorMessage method.

Most widely used CDomain object properties

By default, we assume that WebMail Pro and mail server are installed on the same machine. Thus, it's not required to add any domains, default domain settings will be used with incoming/outgoing mail server name set to localhost.

However, if you might need to add domain to WebMail Pro, that can be done with the code of the following kind:

<?php
// determining main directory
defined('WM_ROOTPATH') || define('WM_ROOTPATH', (dirname(__FILE__).'/../'));
 
// utilizing WebMail Pro API
include_once WM_ROOTPATH.'libraries/afterlogic/api.php';
if (class_exists('CApi') && CApi::IsValid())
{
  // Getting required API class
  $oApiDomainsManager = CApi::Manager('domains');
 
  // Creating domain object
  $oDomain = new CDomain('domain.com');
 
  // Additional modification of domain details
  $oDomain->IncomingMailProtocol = EMailProtocol::IMAP4;
  $oDomain->IncomingMailServer = 'imap.domain.com';
  $oDomain->OutgoingMailServer = 'smtp.domain.com';
 
  if ($oApiDomainsManager->CreateDomain($oDomain))
  {
    echo 'Domain '.$oDomain->Name.' is created successfully.';
  }
  else
  {
    echo $oApiDomainsManager->GetLastErrorMessage();
  }
}
else
{
  echo 'WebMail API not allowed';
}

As you can see, domain is added with IMAP selected for protocol type. For POP3, supply the respective value:

  $oDomain->IncomingMailProtocol = EMailProtocol::POP3;

Advanced login

Method LoginToAccountEx

Logs user into specified email account. Accepts full range of incoming/outgoing server connection parameters, does not rely on Domains configuration in AdminPanel. In case if the account was not created in WebMail yet but user can log into it, account will be created.

Parameters:

Returns CAccount object on success, false on error. Error message can be retrieved using GetLastErrorMessage method.

Standard login mode of WebMail Pro provides fields for login ID (which normally matches email address) and password. There's also Advanced Login mode which allows for supplying full set of login details: both login ID and email address, hosts and ports for incoming/outgoing email etc.

The same approach can be implemented using the API. If you're interested in this, check examples/login-to-account-ex.php sample.

Deleting domain

Method DeleteDomainByName

Deletes the domain from WebMail Pro database.

Parameters:

Returns true on success and false on error. Error message can be retrieved using GetLastErrorMessage method.

You can also delete a domain you have added. It would work regardless of whether it was added via AdminPanel directly or via integration API. However, domain should not contain any users, otherwise it cannot be deleted.

<?php
// Example of removing a domain
 
// determining main directory
defined('WM_ROOTPATH') || define('WM_ROOTPATH', (dirname(__FILE__).'/../'));
 
// utilizing WebMail Pro API
include_once WM_ROOTPATH.'libraries/afterlogic/api.php';
if (class_exists('CApi') && CApi::IsValid())
{
  // Getting required API class
  $oApiDomainsManager = CApi::Manager('domains');
 
  $sDomainToDelete = 'domain.com';
  if ($oApiDomainsManager->DeleteDomainByName($sDomainToDelete))
  {
    echo 'Domain '.$sDomainToDelete.' is deleted successfully.';
  }
  else
  {
    // failed to delete domain
    echo $oApiDomainsManager->GetLastErrorMessage();
  }
}
else
{
  echo 'WebMail API not allowed';
}

Removing user account

Method DeleteAccountByEmail

Locates user account based on email address and deletes it from WebMail Pro database.

Parameters:

Returns true on success and false on error. Error message can be retrieved using GetLastErrorMessage method.

<?php
// Example of removing an account
 
// determining main directory
defined('WM_ROOTPATH') || define('WM_ROOTPATH', (dirname(__FILE__).'/../'));
 
// utilizing WebMail Pro API
include_once WM_ROOTPATH.'libraries/afterlogic/api.php';
if (class_exists('CApi') && CApi::IsValid())
{
  // data for deleting the account
  $sAccountToDelete = 'test@localhost';
 
  // Getting required API class
  $oApiUsersManager = CApi::Manager('users');
 
  if ($oApiUsersManager->DeleteAccountByEmail($sAccountToDelete))
  {
    echo 'Account '.$sAccountToDelete.' was removed successfully.';
  }
  else
  {
    // failed to delete account
    echo $oApiUsersManager->GetLastErrorMessage();
  }
}
else
{
  echo 'WebMail API not allowed';
}

More examples

WebMail Pro contains a number of integration samples under examples directory, and we're going to add more examples in the future.

One useful example is clear-tmp.php script which can be launched via crontab, say, once a day to ensure removal of temporary files.

Last edit: 2011/5/20