Creating user accounts via API

In this sample, we will cover creating new user accounts in MailSuite Pro, which also means creating new email addresses on mail server side. We'll be using Web API for this purpose, as well as PHP API later.

Using Web API

Please note that adminpanel of MailSuite Pro uses this same approach, so if you're having troubles using Web API to manage accounts, domains, settings etc., it's a good idea to study Web API requests and responses in adminpanel using web browser console.

The example demonstrates the use of Web API in PHP but this approach can be used in any other language capable of sending web/AJAX requests. Strictly speaking, there's no need for the requests to be asynchronous, while for many languages and platforms, that can be a requirement. We're using the following function to send web requests to server:

function postdata($sUrl, $aPost, $sToken="") {
    $rCurl = curl_init();
    $acurlOpt = array(
        CURLOPT_URL => $sUrl,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($aPost),
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
    );
    if ($sToken!="") {
        $acurlOpt[CURLOPT_HTTPHEADER] = array("Authorization: Bearer ".$sToken);
    }
    curl_setopt_array($rCurl, $acurlOpt);
    $mResult = curl_exec($rCurl);
    curl_close($rCurl);
    $oResult = ($mResult !== false) ? json_decode($mResult) : null;
    return $oResult;
} 

To have access to administrative features like creating users, we need to log in as superadmin first. Upon successful authentication, we'll get authentication token which will be sent in headers of all the subsequent requests:

$sParams = '{"Login":"superadmin","Password":"12345"}';
$aData = array("Module"=>"AdminAuth", "Method"=>"LoginAsSuperadmin", "Parameters"=>$sParams);
 
$oResult = postdata("https://your.server.URL/?/Api/", $aData);
if (isset($oResult->Result->AuthToken)) {
  $sAuthToken = $oResult->Result->AuthToken;

Note that API access URL is obtained by adding /?/Api/ to main URL of MailSuite Pro installation.

After getting authentication token, we can proceed with creating user account. That's done by calling CreateUser method of Core module, all the required steps such as tenant/domain lookup and creating mailbox on server will be done automatically with this method call.

It's assumed that domain is already added in MailSuite Pro adminpanel.

$sEmail = "username@domain.com";
$sPassword = "...";
 
$sParams = '{"UserId":0,"TenantId":0,"Role":2,"WriteSeparateLog":false,"Forced":true,"PublicId":"'.$sEmail.'","DomainId":0,"QuotaBytes":0,"Password":"'.$sPassword.'"}';
$aData = array("Module"=>"Core", "Method"=>"CreateUser", "Parameters"=>$sParams);
$oResult=postdata($sURL, $aData, $sAuthToken);
 

Currently, Web API doesn't allow for checking whether email account already exists, so we're sending a request, and should it fail with specific ErrorCode, we can tell that such user account already exists.

Below, you will find a complete sample of creating account via Web API.

<?php
function postdata($sUrl, $aPost, $sToken="") {
    $rCurl = curl_init();
    $acurlOpt = array(
        CURLOPT_URL => $sUrl,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($aPost),
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
    );
    if ($sToken!="") {
        $acurlOpt[CURLOPT_HTTPHEADER] = array("Authorization: Bearer ".$sToken);
    }
    curl_setopt_array($rCurl, $acurlOpt);
    $mResult = curl_exec($rCurl);
    curl_close($rCurl);
    $oResult = ($mResult !== false) ? json_decode($mResult) : null;
    return $oResult;
}
 
$sUrl = "http://192.168.0.1/?/Api/";
$sEmail="username@domain.com";
$sPassword="...";
 
$sParams = '{"Login":"superadmin","Password":"12345"}';
$aData=array("Module"=>"AdminAuth", "Method"=>"LoginAsSuperadmin", "Parameters"=>$sParams);
$oResult=postdata($sUrl, $aData);
 
if (isset($oResult->Result->AuthToken)) {
  $sAuthToken=$oResult->Result->AuthToken;
  $sParams = '{"UserId":0,"TenantId":0,"Role":2,"WriteSeparateLog":false,"Forced":true,"PublicId":"'.$sEmail.'","DomainId":0,"QuotaBytes":0,"Password":"'.$sPassword.'"}';
  $aData = array("Module"=>"Core", "Method"=>"CreateUser", "Parameters"=>$sParams);
  $oResult=postdata($sUrl, $aData, $sAuthToken);
 
  if (isset($oResult->ErrorCode)) {
    if ($oResult->ErrorCode === 111) {
      echo "User already exists";
    } else {
      echo "Cannot create user";
    }
  } else {
    echo "User created successfully";
  }
} else {
  echo "Cannot authenticate via API";
}

Now let's improve this example by adding batch operation. Create cr.txt file with content like this:

a@localhost | p123
a2@localhost | p232
a3@localhost | p333
a4@localhost | p444

We'll be creating accounts with email addresses and passwords listed there:

<?php
function postdata($sUrl, $aPost, $sToken="") {
    $rCurl = curl_init();
    $acurlOpt = array(
        CURLOPT_URL => $sUrl,
        CURLOPT_CUSTOMREQUEST => "POST",
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($aPost),
        CURLOPT_SSL_VERIFYPEER => false,
        CURLOPT_RETURNTRANSFER => true,
    );
    if ($sToken!="") {
        $acurlOpt[CURLOPT_HTTPHEADER] = array("Authorization: Bearer ".$sToken);
    }
    curl_setopt_array($rCurl, $acurlOpt);
    $mResult = curl_exec($rCurl);
    curl_close($rCurl);
    $oResult = ($mResult !== false) ? json_decode($mResult) : null;
    return $oResult;
}
$sEOL = (PHP_SAPI === 'cli')?PHP_EOL: "<BR/>";
 
$sUrl = "http://192.168.0.1/?/Api/";
$sParams = '{"Login":"superadmin","Password":"12345"}';
 
$aData=array("Module"=>"AdminAuth", "Method"=>"LoginAsSuperadmin", "Parameters"=>$sParams);
$oResult=postdata($sUrl, $aData);
 
if (isset($oResult->Result->AuthToken)) {
  $sAuthToken=$oResult->Result->AuthToken;
//  die ($sAuthToken);
  $file = file ("cr.txt");
  foreach ($file as $line) {
    if (strpos($line," | ")!==false) {
      $aLine = explode(" | ",$line); $sEmail = trim($aLine[0]); $sPassword = trim($aLine[1]);
      $sParams = '{"UserId":0,"TenantId":0,"Role":2,"WriteSeparateLog":false,"Forced":true,"PublicId":"'.$sEmail.'","DomainId":0,"QuotaBytes":0,"Password":"'.$sPassword.'"}';
      $aData = array("Module"=>"Core", "Method"=>"CreateUser", "Parameters"=>$sParams);
      $oResult=postdata($sUrl, $aData, $sAuthToken);
 
      if (isset($oResult->ErrorCode)) {
        if ($oResult->ErrorCode === 111) {
          echo "User $sEmail already exists".$sEOL;
        } else {
         echo "Cannot create user $sEmail ($sPassword)".$sEOL;
        }
    } else {
        echo "User $sEmail created successfully".$sEOL;
    }
  }}
} else {
  echo "Cannot authenticate via API".$sEOL;
}

Note that the script can be run from web browser as well as from command line PHP.

Using PHP API

This sample is rather straightforward, we check if domain exists, locate its mailserver entry, create user and email account for that user.

include __DIR__.'/system/autoload.php';
\Aurora\System\Api::Init(true);
$oCoreDecorator = \Aurora\System\Api::GetModuleDecorator('Core');
$oMailDecorator = \Aurora\System\Api::GetModuleDecorator('Mail');
$oDomainsDecorator = \Aurora\System\Api::GetModuleDecorator('MailDomains');
 
$sDomain = "domain.com";
$sUser = "username-here";
$sPassword = "password-here";
$sPublicId = $sUser."@".$sDomain;
 
$oDomain = $oDomainsDecorator->getDomainsManager()->GetDomainByName($sDomain ,0);
if (!$oDomain) exit("Domain not found");
 
$aServer = $oMailDecorator->GetMailServerByDomain($sDomain);
if (!isset($aServer["Server"])) exit("Server not found");
$oServer = $aServer["Server"];
 
$oUser = $oCoreDecorator->getUserByPublicId($sPublicId);
if ($oUser instanceof \Aurora\Modules\Core\Models\User) exit("User already exists");
$iUserId = $oCoreDecorator->CreateUser(0, $sPublicId);
\Aurora\Modules\Mail\Module::Decorator()->CreateAccount($iUserId, '', $sPublicId, $sPublicId, $sPassword, $oServer->toResponseArray());