Manually Testing the cPanel API Using a Perl Script

You can manage much of a cPanel hosting account from a script instead of clicking through the control panel: list email accounts, create a mailbox, read disk usage and more. This guide shows how to test the cPanel API by hand with a short Perl script, using an API token you create in your own cPanel account. It is written for Domain India cPanel hosting customers and beginner developers.

1. Which cPanel API you can use

cPanel has several APIs, and older guides mix them up.

As a Domain India shared hosting customer you own one cPanel account, so UAPI is the API for you. Scripts that send Authorization: whm … to port 2087, as many older examples do, are for WHM and will not work with a cPanel account token.

2. Create an API token

3. The Perl test script

This script calls one UAPI function and prints the result. It uses only modules that ship with Perl (HTTP::Tiny and JSON::PP), reads the token from an environment variable so it never sits in the file, and keeps certificate checking on.

#!/usr/bin/perl
use strict;
use warnings;
use HTTP::Tiny;
use JSON::PP qw(decode_json);

my $host   = $ENV{CPANEL_HOST}  or die "Set CPANEL_HOST\n";   # server name from the client area
my $user   = $ENV{CPANEL_USER}  or die "Set CPANEL_USER\n";   # your cPanel username
my $token  = $ENV{CPANEL_TOKEN} or die "Set CPANEL_TOKEN\n";  # the API token
my $module = shift // 'DomainInfo';
my $func   = shift // 'list_domains';
my %args   = map { split /=/, $_, 2 } @ARGV;                  # extra key=value arguments

my $ua  = HTTP::Tiny->new(
    verify_SSL      => 1,
    timeout         => 30,
    default_headers => { Authorization => "cpanel $user:$token" },
);
my $url = "https://$host:2083/execute/$module/$func";
$url .= '?' . $ua->www_form_urlencode(\%args) if %args;

my $res = $ua->get($url);
die "HTTP $res->{status} $res->{reason}\n$res->{content}\n" unless $res->{success};

my $data = decode_json($res->{content});
if ($data->{status}) {
    print JSON::PP->new->pretty->canonical->encode($data->{data});
} else {
    print "API error: ", join('; ', @{ $data->{errors} || [] }), "\n";
}

Save it as uapi-test.pl. The script takes the module and function names as its first two arguments, followed by any key=value arguments the function needs.

4. Run it

The easiest place to run the script is your own computer. Perl is installed on macOS and most Linux systems; on Windows, install Strawberry Perl. HTTPS in HTTP::Tiny needs the IO::Socket::SSL module; check it with perl -MIO::Socket::SSL -e1 and install it with your package manager or cpanm IO::Socket::SSL if that command prints an error.

export CPANEL_HOST="server-name-from-client-area"
export CPANEL_USER="yourcpaneluser"
export CPANEL_TOKEN="paste-the-token-here"

perl uapi-test.pl DomainInfo list_domains
perl uapi-test.pl Email list_pops
perl uapi-test.pl Quota get_quota_info

For CPANEL_HOST, use the server name shown for your hosting service in the client area (the Manage › Access tab lists your username, server and panel URL). Using the server name rather than a bare IP address lets certificate checking pass.

A successful call prints the data part of the response. Every UAPI response has the same shape: status (1 for success, 0 for failure), errors, warnings, messages, data and metadata, so your scripts can check status first.

5. Useful UAPI functions to try

Start with read-only functions such as list_domains and list_pops. Test anything that changes the account, like add_pop, on a test address first. The full list of modules and functions is in cPanel's official UAPI documentation.

On the command line, arguments go after the function name, for example perl uapi-test.pl Email add_pop email=test domain=example.com password='Str0ng-Pass!' quota=1024. Avoid typing real passwords into shell history on a shared computer.

6. Troubleshooting

7. Running this on Domain India

• Shared cPanel hosting: port 2083 is open on our cPanel servers, and Manage API Tokens is in every cPanel account, so the script above works from your own computer. Jailed SSH is available on every shared hosting plan; it is off by default, so ask support to enable it for your account. Tools available inside the jailed shell vary, so if you want to run scripts on the server itself, ask support what is available.
• WHM API: shared hosting accounts have no WHM access, so WHM API 1 calls on port 2087 are not available to them. Our VPS plans do not offer cPanel, so WHM is not part of them either.
• Scheduled scripts: if you want the script to run on a schedule, run it from your own machine or a server you control; keep the token outside the script, as above.

Frequently asked questions

Ready to try it? Log in through how to log in to cPanel, create a token under Security, and run the script against a read-only function first. If you need SSH on your account, see enabling and accessing jailed SSH.