cPanel-API (UAPI): E-Mail, FTP und Umleitungen per SSH, cURL oder PHP automatisieren

Die cPanel-API (UAPI) gibt Zugriff auf fast alle Funktionen Ihres Kontos: E-Mail-Konten anlegen, Umleitungen, Backups, Statistiken abfragen … Damit können Sie wiederkehrende Aufgaben automatisieren oder cPanel mit Ihren eigenen Werkzeugen verbinden, zum Beispiel um das E-Mail-Konto eines neuen Mitarbeiters aus Ihrem Intranet heraus anzulegen.

Es gibt zwei Möglichkeiten, sie zu nutzen:

• Im eigenen Konto per SSH mit dem Befehl uapi. Es ist keine zusätzliche Authentifizierung nötig.
• Von außen mit HTTPS-Aufrufen an Port 2083 von cPanel, authentifiziert mit einem Token.

Alle Aufrufe folgen demselben Schema: ein Modul (Email, Mime, Ftp …), eine Funktion (list_pops, add_redirect …) und ihre Parameter. Suchen Sie die benötigte Funktion in der UAPI-Dokumentation und passen Sie eines der Beispiele aus diesem Artikel an.

Die API per SSH mit dem Befehl uapi nutzen

Wenn die Automatisierung im Hosting selbst läuft (ein Skript, ein Cron-Job), melden Sie sich per SSH an und verwenden Sie den Befehl uapi. Er wirkt immer auf Ihr Konto, mit Ihrem Benutzer.

Eine Umleitung anlegen

Um dominio1.com mit einer permanenten Umleitung (301) auf https://dominio2.com umzuleiten, verwenden Sie die Funktion Mime add_redirect:

uapi --output=jsonpretty \
  Mime \
  add_redirect \
  domain='dominio1.com' \
  redirect='https://dominio2.com/' \
  redirect_www=0 \
  type='permanent'

• domain: die Domain, die Sie umleiten möchten.
• redirect: die Zieladresse.
• type: permanent (301) oder temp (302). Wenn Sie testen, verwenden Sie temp: Browser speichern 301-Umleitungen, und danach sind Änderungen schwer zu sehen.
• redirect_www: 0 leitet mit und ohne www um; 1 nur mit www; 2 nur ohne www.

Die Antwort zeigt an, ob sie angelegt wurde. Achten Sie auf status: 1 und darauf, dass errors leer ist.

Mit --output= wählen Sie das Format der Antwort: json, jsonpretty oder yaml (der Standardwert).

Die E-Mail-Konten auflisten

Die Funktion Email list_pops gibt alle E-Mail-Konten zurück:

uapi Email list_pops

apiversion: 3
func: list_pops
module: Email
result:
  data:
    -
      email: cuenta1@dominio.com
      login: cuenta1@dominio.com
      suspended_incoming: 0
      suspended_login: 0
  errors: ~
  messages: ~
  status: 1
  warnings: ~

Um nur die Adressen zu erhalten, eine pro Zeile:

uapi Email list_pops | grep 'email:' | awk -F ': ' '{print $2}'

cuenta1@dominio.com
cuenta2@dominio.com
cuenta3@dominio.com

Wenn Sie lieber mit JSON arbeiten, erledigt jq das zuverlässiger:

uapi --output=json Email list_pops | jq -r '.result.data[].email'

Um die Liste in einer Datei zu speichern, hängen Sie > correos.txt an den Befehl an. Wenn die Datei existiert, wird sie überschrieben.

Der Befehl uapi funktioniert per SSH und in Cron-Jobs. Aus PHP heraus nicht: In unserem Hosting sind die Funktionen, die Befehle ausführen (exec, shell_exec, system …), aus Sicherheitsgründen deaktiviert. Wenn Sie die API aus einem PHP-Skript brauchen, auch wenn es im selben Hosting liegt, rufen Sie sie per HTTPS mit einem Token auf, wie im Folgenden erklärt.

Die API von einem anderen Server mit einem Token nutzen

Das Token erstellen

Öffnen Sie in cPanel Sicherheit > API-Token verwalten (Manage API Tokens) und klicken Sie auf Erstellen. Geben Sie ihm einen Namen, der die Integration erkennen lässt, und, wenn es für etwas Vorübergehendes ist, ein Ablaufdatum.

cPanel zeigt Ihnen das Token nur einmal an: Kopieren Sie es und bewahren Sie es sicher auf. Wer das Token hat, kann in Ihrem Konto alles tun. Legen Sie es also nicht in öffentlichen Code oder in Dateien innerhalb von public_html. Wenn es nicht mehr verwendet wird oder Sie glauben, dass es durchgesickert ist, widerrufen Sie es auf derselben Seite.

Aufrufe mit cURL

curl -H 'Authorization: cpanel USUARIO:TOKEN' \
  'https://tudominio.com:2083/execute/Modulo/funcion?parametro=valor'

• USUARIO: Ihr cPanel-Benutzer.
• TOKEN: das Token, das Sie erstellt haben.
• tudominio.com: eine beliebige Domain Ihres Kontos, die auf das Hosting zeigt und ein aktives SSL-Zertifikat hat. Der Servername funktioniert ebenfalls.

Die Adresse folgt immer dem Format execute/Modulo/funcion?parametro=valor. Wenn Sie mehrere Parameter brauchen, trennen Sie sie mit &.

Zum Beispiel, um die E-Mail-Konten aufzulisten:

curl -H 'Authorization: cpanel USUARIO:TOKEN' \
  'https://tudominio.com:2083/execute/Email/list_pops'

Die Antwort kommt als JSON. Prüfen Sie status (muss 1 sein) und errors: Eine HTTP-Antwort 200 kann einen API-Fehler enthalten.

Den Spam-Ordner leeren

Die Funktion SpamAssassin clear_spam_box leert den Spam-Ordner aller E-Mail-Konten Ihres Hostings:

curl -H 'Authorization: cpanel USUARIO:TOKEN' \
  'https://tudominio.com:2083/execute/SpamAssassin/clear_spam_box'

Um Aufrufe ohne Code zu testen, ist ein REST-Client wie Insomnia oder Postman praktisch.

Derselbe Aufruf in PHP mit cURL:

<?php
$username = 'USUARIO_CPANEL';
$token    = 'TOKEN';
$domain   = 'tudominio.com';

$query = 'https://' . $domain . ':2083/execute/SpamAssassin/clear_spam_box';

$curl = curl_init($query);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_TIMEOUT, 30);
curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Authorization: cpanel ' . $username . ':' . $token,
]);

$result = curl_exec($curl);
if ($result === false) {
    error_log('Error en la llamada a cPanel: ' . curl_error($curl));
}
curl_close($curl);

$data = json_decode($result, true);
echo ($data['status'] ?? 0) == 1 ? "Spam vaciado\n" : "Error: " . implode(', ', $data['errors'] ?? []) . "\n";

Deaktivieren Sie nicht die SSL-Prüfung (CURLOPT_SSL_VERIFYPEER): Wenn ein Zertifikatsfehler auftritt, verwenden Sie eine Domain mit gültigem SSL oder den Servernamen.

Aufrufe aus Laravel

Wenn Sie Laravel oder ein anderes Projekt mit Composer verwenden, vereinfacht der HTTP-Client (oder Guzzle) die Aufrufe. Speichern Sie die Daten in der .env und lesen Sie sie in config/services.php aus:

// config/services.php
'cpanel' => [
    'domain'   => env('CPANEL_DOMAIN'),
    'username' => env('CPANEL_USERNAME'),
    'token'    => env('CPANEL_TOKEN'),
],

Spam leeren:

use Illuminate\Support\Facades\Http;

$cpanel = config('services.cpanel');

$response = Http::withToken($cpanel['username'] . ':' . $cpanel['token'], 'cpanel')
    ->get('https://' . $cpanel['domain'] . ':2083/execute/SpamAssassin/clear_spam_box')
    ->throw();

$response->json('status'); // 1, wenn es geklappt hat

Die FTP-Konten auflisten

Mit Ftp list_ftp ändert sich nur die Adresse:

$response = Http::withToken($cpanel['username'] . ':' . $cpanel['token'], 'cpanel')
    ->get('https://' . $cpanel['domain'] . ':2083/execute/Ftp/list_ftp')
    ->throw();

$cuentas = $response->json('data');

Ein E-Mail-Konto anlegen

Die Funktion Email add_pop legt ein Postfach an. Sie braucht mindestens die Adresse und das Passwort; mit quota legen Sie die Größe in MB fest (0 ist unbegrenzt). Senden Sie die Daten per POST, damit das Passwort weder in der URL noch in den Serverprotokollen landet:

$response = Http::withToken($cpanel['username'] . ':' . $cpanel['token'], 'cpanel')
    ->asForm()
    ->post('https://' . $cpanel['domain'] . ':2083/execute/Email/add_pop', [
        'email'    => 'nuevo@tudominio.com',
        'password' => 'ContraseñaLarga-y-Segura',
        'quota'    => 2048,
    ])
    ->throw();

if ($response->json('status') != 1) {
    throw new RuntimeException(implode(', ', $response->json('errors') ?? []));
}

Wenn das Passwort schwach ist, lehnt cPanel das Konto ab und erklärt es in errors.

Mit diesen Bausteinen können Sie Aufrufe verketten und vollständige Abläufe aufbauen: Anlegen von Mitarbeitern, regelmäßiges Aufräumen, Berichte … Wenn ein Aufruf, der Daten ändert, wegen einer Zeitüberschreitung abbricht, prüfen Sie den Status, bevor Sie ihn wiederholen: Möglicherweise wurde er trotzdem ausgeführt.