MailSuite Pro documentation

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. 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 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";
}