Creating Email Accounts Using PHP: A Step-by-Step Guide

If your application needs to create mailboxes automatically, for example one for each new staff member or client, you can do it from PHP by calling your control panel's API instead of clicking through the panel. On cPanel hosting that means cPanel's UAPI, authenticated with an API token that you create in your own cPanel account. This guide shows how to do it safely.

1. Do you need an API at all?

For a handful of mailboxes, the control panel is quicker and safer: see how to create email accounts for your domain. Use the API when mailboxes are created as part of a process, such as onboarding in an HR or client-management system.

The method below is for cPanel hosting. It uses only your own cPanel account's permissions: no root, WHM or reseller access is involved. DirectAdmin and Webuzo have their own APIs, which this guide does not cover; ask support before you build on them.

2. Create an API token

You also need the server host name and your cPanel username. Both are in your client area: open the hosting service at Services › Hosting, then the Manage › Access tab. cPanel's API listens on port 2083 over HTTPS, the same port as the cPanel login.

3. Store the settings outside the web root

Put the settings in a file one level above public_html, for example /home/USERNAME/config/cpanel.php:

<?php
return [
    'host'  => 'server.example.com',   // from the Access tab
    'user'  => 'USERNAME',             // your cPanel username
    'token' => 'PASTE-YOUR-TOKEN-HERE',
];

4. Create the mailbox

The UAPI function is Email::add_pop. It takes the part before the @ as email, your domain as domain, a password, and a quota in megabytes (0 means no quota, within your plan's limits).

<?php
function cpanel_uapi(string $module, string $function, array $params): array
{
    $cfg = require '/home/USERNAME/config/cpanel.php';
    $url = sprintf('https://%s:2083/execute/%s/%s', $cfg['host'], $module, $function);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => http_build_query($params),
        CURLOPT_HTTPHEADER     => ['Authorization: cpanel ' . $cfg['user'] . ':' . $cfg['token']],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
        // SSL verification stays ON (the default). Never set CURLOPT_SSL_VERIFYPEER to false.
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $err  = curl_error($ch);
    curl_close($ch);

    if ($body === false) {
        throw new RuntimeException("Connection failed: $err");
    }
    if ($code !== 200) {
        throw new RuntimeException("cPanel returned HTTP $code");
    }
    return json_decode($body, true, 512, JSON_THROW_ON_ERROR);
}

$local = strtolower(trim($_POST['mailbox'] ?? ''));
if (!preg_match('/^[a-z0-9][a-z0-9._-]{0,63}$/', $local)) {
    exit('Invalid mailbox name');
}
$password = bin2hex(random_bytes(12)); // or a password your user sets

$result = cpanel_uapi('Email', 'add_pop', [
    'email'    => $local,
    'domain'   => 'yourdomain.com',
    'password' => $password,
    'quota'    => 1024,
]);

if (($result['status'] ?? 0) === 1) {
    echo "Created {$result['data']}";
} else {
    echo 'Could not create the mailbox: ' . implode('; ', $result['errors'] ?? ['unknown error']);
}

Show the new password to the person once, over HTTPS, or let them set it themselves. Never write it to a log file or send it in a plain email.

5. Read the reply correctly

UAPI returns HTTP 200 with a JSON body even when the action fails, so always check status, not only the HTTP code:

A 401 or 403 HTTP code means the token or username is wrong, the token has expired, or it was revoked.

Common reasons for status 0:

• The address already exists. Check first with Email::list_pops, or treat this error as "already done".
• The password is too weak. cPanel rejects passwords below its strength threshold. Generate a long random one.
• The plan's limit is reached. Every plan allows a set number of email accounts. Delete unused ones or upgrade.
• The domain is not on the account. domain must be your main domain, an addon domain or a subdomain of the account.

6. Where to run the script

• On a different server (your application's own server, for example): that server must reach port 2083 on your hosting server, which is open.
• On the same cPanel account: curl_exec is available on our cPanel servers, so the code above runs from your hosting account as well. Test it once; if the connection times out, ask support.

On our DirectAdmin servers curl_exec is usually disabled for websites, which is one more reason this guide sticks to cPanel.

7. Keep the endpoint safe

A script that creates mailboxes is a tempting target. If spammers find it, they can create accounts and send spam from your domain, which gets your mail blocked.

• Put it behind your application's login, and check that the user is allowed to create mailboxes.
• Accept only the part before the @, validated as in the example. Never let the request choose the domain.
• Add CSRF protection and a rate limit.
• Log who created which mailbox and when, but never the password.

Mail sent from new mailboxes counts towards your account's outgoing limit: 200 messages per hour per account on cPanel.

8. Where Domain India fits

Every cPanel plan includes email accounts on your domain, and each plan sets how many you can create; the plan card shows the number. If you need mailboxes with calendar and contacts that you add and remove from the client area, and don't need an API, look at Business Email, which is priced per mailbox.

Prices on the cards are Domain India list prices and exclude 18% GST.

Ready to automate? Create your token in cPanel, or read how to create email accounts for your domain if the panel is enough. If a request fails and the error is unclear, open a support ticket with the error text.