cPanel

cPanel is a Linux based web hosting control panel that provides a graphical interface and automation tools designed to simplify the process of hosting web sites.

Many of our customers use the Halon platform as a premium anti-spam in front of their cPanel servers. There are numerous of different integration opportunities, and our official plugins only scratch the surface of what is possible. The most advanced integrations are co-developed by us and the hosting provider, on a project basis.

One-click end-user login

The end-user supports on-the-fly (session-based) access levels (domain or email based), which our cPanel module can prepare via the session-transfer.php file.

Fetching cPanel information

You might want the end-user to fetch some information from the cPanel API, for example, Email::list_forwarders. We have done many such integrations, and can help you to tailor the systems to fit perfectly.

Dynamic routing

A fast and simple solution, to get started with the integration of Halon and cPanel, is to use a dynamic routing checking the mail hostname of the recipient's domain, e.g. mail.example.com. If the IP address belongs to one of our cPanel servers, it is used to perform a recipient lookup, after which the email can be transported to the fully qualified domain name.

First, make sure that the cPanel's email routing is set to Local Mail Exchanger under Email Routing -> Configure Email Routing.

Note: If your cPanel environment is not using a common hostname that points to the correct cPanel server, you will need to create one and modify the code. By default, cPanel adds this hostname with the cPanel's IP address.

Then, create a new plain-text file under Configuration -> Email engine -> Code editor with the ID cpanelnetwork. Now, add all IP addresses to your cPanel servers, each on an own row. It is also possible to use a subnet mask, e.g. 10.0.0.0/24.

Now create one more file (code) with the ID cpanelrouting, and add the following script code into it.

function lookup_cpanelserver ($recipientdomain) {
    $fqdn = "mail." + $recipientdomain;
    $ips = dns($fqdn);
    if (!$ips) return 0;
    foreach (file("file:cpanelnetwork") as $cpanelnetwork) {
        if (in_network($ips[0], $cpanelnetwork)) {
            echo "Found matching cpanel server for " + $fqdn + " (" + $ips[0] + ")";
            return $fqdn;
        }
    }
    return 0;
}

In the RCPT TO context under Configuration -> Email engine -> Script mappings, add the following script code, to enable the lookups towards your cPanel servers.

include_once "file:cpanelrouting";

// Dynamic recipient lookup
$cpanelserver = cache ["ttl" => 3600, "size" => 2048, "ttl_override" => [0 => 1800]] lookup_cpanelserver($recipientdomain);

if ($cpanelserver) {
    $result = cache [
            "ttl_function" => function ($result) {
                $code = $result["error_code"];
                if ($code == -1)
                    return 60;
                if ($code >= 200 and $code <= 299)
                    return 86400;
                return 300;
            },
            "size"=> 16384,
        ]
        smtp_lookup_rcpt(["host" => $cpanelserver], "", $recipient, ["error_code" => true]);
    if ($result["error_code"] == -1) {
        $error = true;
        $errormsg = "SMTP recipient lookup failed";
    }
    if ($result["error_code"] >= 200 and $result["error_code"] <= 299) {
        $context["dynamicroute"] = true;
        Accept();
    }
    if ($result["error_code"] >= 400 and $result["error_code"] <= 499)
        $error = true;
    if ($result["error_code"] >= 400 and $result["error_code"] <= 599)
        $errormsg = $result["error_message"];

    if ($error ?? false)
        Defer($errormsg ?? "");
    else
        Reject($errormsg ?? "");
}

Now, to finalise the integration, two more parts must be added to your incoming flow. In the DATA context, add the following script code at the top of the page.

if ($context["dynamicroute"] == true) {
    SetMetaData(["dynamicroute" => "yes"]);
}

And in the pre-delivery context under Configuration -> Email engine -> Code editor, add the following code, so it can be delivered to the correct server.

include_once "file:cpanelrouting";

$metadata = GetMetaData();

if ($metadata["dynamicroute"] == "yes") {
    $cpanelserver = cache ["ttl" => 3600, "size" => 2048, "ttl_override" => [0 => 1800]] lookup_cpanelserver($recipientdomain);
    if (!$cpanelserver) 
        Reschedule(rand(1, 300), ["reason" => "Mailserver for $recipientdomain not found", "increment_retry" => false]);
    SetDestination($cpanelserver);
    Try();
}

If there is no pre-delivery script, it must be created; click on the Add button and choose pre-delivery as type.