PHP Script to create Add-on Domain in cPanel via XML-API

whm-0 I know, I have been away for a while and the point of this blog being the place where I document challenges I face seems somewhat lost but alas….recovery of that point is nigh.

Now, this may not be a problem that many people face but getting good sample code from the cPanel XML-API documentation is a bust. They do have a nice Forum though, where it is possible to get the answers one may seek but forums involve a lot of reading which I try to avoid when looking for what should be quick solutions.

I have therefore decided to document something that I figured would only take me a couple of minutes to figure out, only for it to kill four precious hours. So here goes…

PHP script to programmatically create an add-on domain in cPanel.

First, you will need to download cPanel’s XML-API for PHP which you can find in the links below.

Github – (original download from cPanel Inc.) Link – cPanel PHP XML-API (includes file with changes below)

We will be using an API2 function to add an add-on domain and we will need to parse some data to the function. So let’s look at the example code in api2_example_withargs.php that is included with the above download:

include ‘xmlapi.php’;

$ip = ‘’;
$root_pass = ‘password’;

$account = ‘someuser’;
$email_account = ‘randomemail’;
$email_domain = ‘’;

$xmlapi = new xmlapi($ip);

print $xmlapi->api2_query($account, ‘Email’, ‘getdiskusage’, array(domain=>$email_domain, login=>$email_account) );

In the above example…

  1. the IP is the IP address of your server. (You could use a hostname here, but using an IP gives you a slight performance improvement.)
  2. $root_pass stores the password you want to login to the XML API with. If you are logging in as a cPanel user, you can store the cPanel user’s password in this variable.
  3. $account is the cPanel user you want to perform this action on.

Many people use the API as a reseller or root user, but you can login as a cPanel user. So if you’re not logging into the API as the root user, just replace:




Now to the heart of the matter.

With these API2 function calls, the first parameter is expected to be the cPanel account we want to perform this action upon, the second parameter is the Module, the third parameter the function to call and the fourth parameter is an array of input arguments for the API2 function.

To create an add-on domain, we will use an API2 function, and this function will take four parameters as described earlier. With this in mind, replace the above code

$xmlapi->api2_query($account, "Email", "getdiskusage", array(domain=>$email_domain, login=>$email_account) );


$xmlapi->api2_query($account, "AddonDomain", "addaddondomain", array(newdomain=>"", dir="public_html/example", subdomain=>"example", pass=>"ftpPass") );

This will create an add-on domain on the account, serving content out of public_html/example with a FTP user of example with password ftpPass being created as part of this API call.

Just like in the cPanel interface, creating the FTP user/pass is required. Also, just like cPanel, you can have the addon domain serve content from anywhere within that cPanel account.

Now find below a link with to the XML-API for PHP that includes the file api2_example_addondomain.php with all the above changes. Link – cPanel PHP XML-API

Stand by for more examples to be included into the above download as I continue to tackle more cPanel related issues that are bound to come my way.


It has come to my attention that there is a possibility of getting ACCESS DENIED error when trying the above solution. This may possibly be due to the fact that unless stated otherwise, the API assumes you are logging in with root/reseller credentials on port 2087. Should your WHM or cPanel be on a different port – please add the line of code below to your script to specify which port the API should use


Replace xxxx with the port number your cPanel or WHM is configured to use. Place the above code before the api2_query call



  1. Hi, I have been researching around the net, seeking help on some task automation within my CPanel hosting environment.

    Just wanted to ask if the xmlapi.php is ONLY for reseller/WHM user or end-user of the Cpanel (i.e. I bought the hosting from a hosting company and I am given free a Cpanel to manage my website).


  2. [13-Dec-2013 08:44:51] URL:
    [13-Dec-2013 08:44:51] DATA: cpanel_xmlapi_user=pbtech&cpanel_xmlapi_module=Email&cpanel_xmlapi_func=listpopswithdisk&cpanel_xmlapi_apiversion=2
    [13-Dec-2013 08:44:51] Authentication Header: Authorization: Basic cGJ0ZWNoOk1pY2hhZWxtYW5kZWxhOTY1Nw==

    [13-Dec-2013 08:44:51] RESPONSE:

    i am getting this in my error log.what is the problem

  3. Its great, it work fine. could you please help us to get more on xml-api2 like create & manage ftp/domain/addon etc

  4. Sorry for the late reply Jigesh345 but just tested the code again from my end and it still works perfectly. Could you print the message that you get with debug set to 1 – i then may be able to help from there. Also, you cPanel version would be of help.

  5. when i run code this error is showing, Parse error: syntax error, unexpected ‘=’, expecting ‘)’ in /home2/taqi786/public_html/ on line 39

  6. please help me buddy, m running this script with this code, its showing blank page, this is my code please hep me..

    include ‘../xmlapi.php’;

    $ip = ‘my host ip’;
    $root_pass = ‘mypassword’;

    $account = ‘cpanel user name’;
    $email_account = ‘my website email’;
    $email_domain = ‘domain name’;

    $xmlapi = new xmlapi($ip);



    please help me to resolve this….

  7. Hi,
    I am new here. Would you please tell me how and where i will keep the file and how i can execute the file to upload addons domain. I want upload 50 domain name at a time. It is possible through this API. Your help would be highly appreciable.

  8. To execute the script – all you would need to do is place in anywhere in you public_html folder – where it can be accessed by a browser the call the appropriate url from the browser. You could also use the command line interface to run the script – and for this – it does not matter where the script is located – as long as php can act on it.

    On using the script to create many addon domains – i would simply loop the $xmlapi->api2_query line accordingly with the data containing the domains you want to create – where an array, object database resource

  9. Hi Allan,
    Thanks for sharing all this; I wish i’d have found your page earlier … anyhow, I spent the last 2 weeks coding an interface that allows batch ( from a txt file ) addon domains, subdomains, email and even subdomain delegation ( A records .. )… I would be happy to share this for free to you or anyone else … the reason I’m here though, is due to the only 2 missing puzzles, my Addaddonsomain works, but the deladdondomain is driving me crazy, mainly “You don’t have control of this domain …. my question: what is the difference of the subdomain arg on addaddondomain and the deladdondomain ? the latter on its documentation states a _ ( underscore as subdomain_maindomain whereas on addondomain the subdomain arg is defined differently. I use a whm/cpanel account on a vps and manage about 3000 domains… any idea ? ( I’ve read the cpanel api forum throughly and there is one mention, but without an answer );
    any ideas ???? Txs !!

  10. Hi, I have tried your script to create subdomain or to listips but it gives me “ACCESS DENIED” error. Will you please give me any suggestion, so I can solve this issue.

Leave a Reply