Blesta cPanel Setup: The Easy, Complete Guide to Connecting WHM

A working Blesta cPanel connection is what turns Blesta from an invoicing tool into a hosting business that runs itself. Once it’s set up, a customer orders a plan, pays, and gets a working cPanel account and a welcome email without you lifting a finger. When an invoice goes unpaid, the account is suspended, and when it’s paid, the account comes back. This guide walks through the whole Blesta cPanel setup, from the WHM API token to your first test order, plus the mistakes that trip most people up.

Why Connect Blesta to cPanel?

Without a module, every new hosting order means logging in to WHM, creating the account by hand, copying the password into an email and remembering to come back if the client stops paying. That works for five clients. It doesn’t work for fifty, and it doesn’t work at 2 a.m. when someone in another time zone signs up.

The Blesta cPanel module handles all of it. It ships with Blesta, so there’s nothing to buy or download. It talks to WHM over its API, so it works the same whether you run your own server as root or sell from a reseller account. And because Blesta logs every call it makes, you can see exactly what happened when something goes wrong.

What You Need Before You Start

• A working Blesta install with its cron job running. Provisioning, suspensions and emails all depend on it.
• A WHM login: root on your own server, or a reseller account such as our reseller hosting.
• At least one hosting package (plan) created in WHM, with the disk, bandwidth and feature limits you want to sell.
• A domain you control for the test order at the end.

Step 1: Create a WHM API Token

1. Log in to WHM and search for Manage API Tokens.
2. Click Generate Token and name it something like blesta so you know what it’s for later.
3. Choose its permissions. If you’ll sell reseller accounts, Blesta’s cPanel module docs say to select Everything.
4. Save, and copy the token right away. WHM only shows it once.

The older “Remote Access Key” still appears in some guides, but it’s deprecated. Use an API token. Treat it like a root password: store it in your password manager, never paste it into a support ticket, and if you think it has leaked, revoke it in WHM and generate a new one. Your Blesta cPanel connection will stop working until you paste the new token into the server settings, so plan to do both at once.

Step 2: Install the Blesta cPanel Module

In Blesta, go to Settings > Company > Modules > Available and click Install next to cPanel. It moves to the Installed tab. Click Manage on it, then Add Server.

Step 3: Add Your Server

• Server Label: any name you’ll recognize, like “Indiana Server 1”.
• Hostname: the server’s full hostname, such as server1.example.com.
• User Name: your WHM username (root or your reseller username).
• Token: paste the API token from Step 1.
• Use SSL when connecting to the API: tick it. Always.
• Account Limit: how many accounts this server should hold before Blesta treats it as full.
• Name Servers: the name servers customers should use. These go into the welcome email.

Click Add Server. If Blesta can’t connect, the usual causes are a typo in the hostname, a firewall blocking port 2087 from your Blesta server, or a token copied with an extra space. See the troubleshooting section below for more.

Step 4: Create a Server Group

Even with one server, use a group. It means you can add a second server later without editing every package. On the cPanel module’s manage page, click Add Server Group, name it, and move your server into Assigned Servers. Blesta fills the first server that isn’t full, then moves to the next one.

Step 5: Create Your First Package

1. Go to Packages > Browse and click Create Package.
2. Give it a name and description, and set Module to cPanel.
3. Under Module Options, pick your Server Group, then the cPanel Package (Blesta pulls these from WHM), and the Account Type: Standard, or Reseller with a WHM ACL.
4. Under Pricing, add each term you sell: monthly, yearly, and so on.
5. Write the Welcome Email (see the next step).
6. Add it to a package group so it shows on your order form, then click Create Package.

If the cPanel Package dropdown is empty, Blesta couldn’t read your plans from WHM. Go back and check the server details, or create a plan in WHM first. Repeat this step for each plan you sell. A typical lineup is a starter, a business and a reseller package, all pointing at the same server group.

Step 6: Write a Useful Welcome Email

The Blesta cPanel module gives you tags for the details customers need. These come straight from Blesta’s documentation:

Your hosting account is ready.

Domain: {service.cpanel_domain}
Username: {service.cpanel_username}
Password: {service.cpanel_password}
Server: {module.host_name}

Point your domain to these name servers:
{% for name_server in module.name_servers %}
Name server: {name_server}
{% endfor %}

Add a link to your client area, your support hours and a line about where to find setup guides. A good welcome email cuts your “how do I log in?” tickets close to zero.

Step 7: Place a Test Order

Don’t skip this, because it’s the only way to prove your Blesta cPanel link works end to end. Order the package as a test client using a domain you control, pay with a test or manual payment, and check that:

• the account appears in WHM under List Accounts with the right plan;
• the welcome email arrives with the right details;
• you can log in to cPanel with those details;
• suspending and unsuspending the service from Blesta changes it in WHM too.

Cancel the test service from Blesta when you’re done and confirm the account is removed from WHM. Now you know every part of your Blesta cPanel setup works before a real customer depends on it.

Troubleshooting a Blesta cPanel Connection

When a Blesta cPanel request fails, your first stop is always the module log at Tools > Logs > Module. It shows each request Blesta sent to WHM and the exact response, which is usually enough to point at the problem. The most common errors are:

• Can’t connect at all: the hostname doesn’t resolve, port 2087 is blocked by a firewall such as CSF, or the SSL certificate on the hostname is invalid. Fix the certificate in WHM with AutoSSL rather than turning SSL off.
• Access denied: the token was revoked, copied wrong, or lacks permissions. Generate a new one with the right access.
• Account not created after payment: the cron job isn’t running, the package has no server group, or every server in the group has hit its account limit.
• Username or domain already exists: WHM already has an account with that name. Remove the old account or change the username on the service.

Upgrades, Downgrades and Cancellations

The Blesta cPanel module doesn’t stop at new accounts. When a client moves to a bigger plan, Blesta changes the account’s package in WHM, so disk and bandwidth limits update right away. To allow this, put the plans in the same package group and turn on upgrades and downgrades for that group. When a service is cancelled, Blesta terminates the account in WHM, which removes its files, so make sure clients know to download a backup first.

A Blesta cPanel service also gives clients handy tools in the client area, such as changing their cPanel password and logging in to cPanel with one click, so they don’t need to contact you for everyday tasks.

Tips for a Smooth Blesta cPanel Setup

• Match names: name each Blesta package after its WHM plan so you never wonder which is which.
• Set honest limits: leave room on each server. A full disk causes far more trouble than a second server.
• Review suspension timing: under Settings > Company > Billing/Payment, choose how many days after the due date unpaid services are suspended.
• Back up first: back up Blesta’s database before big changes to packages or modules.

Frequently Asked Questions

Can I connect Blesta to a reseller account instead of root?

Yes. Use your reseller WHM username and an API token created in your reseller WHM. You can only create accounts within your reseller limits.

Can I import existing cPanel accounts into Blesta?

Yes. When adding a service to a client in the admin area, you can add it without provisioning, entering the existing account’s username and domain so Blesta manages it from then on.

Does the Blesta cPanel module cost extra?

No. It’s included with every Blesta license. You only need a cPanel license for the server itself, which your host or reseller plan usually covers.

Can I connect more than one server?

Yes. Add each server in the module, then add it to your server group. Packages that point at the group start using the new server as soon as the earlier ones are full.

Give Customers More After Signup

Once your Blesta cPanel accounts set themselves up, give clients a reason to keep logging in. Caddie for Blesta adds uptime monitoring, SSL and DNS checks and email tools to your client area. See all our Blesta plugins and guides.