API de cPanel (UAPI) : automatiser la messagerie, le FTP et les redirections depuis SSH, cURL ou PHP

L'API de cPanel (UAPI) donne accès à presque toutes les fonctions de votre compte : créer des comptes de messagerie, des redirections, des sauvegardes, consulter des statistiques… Elle vous permet d'automatiser des tâches répétitives ou de connecter cPanel à vos propres outils, par exemple pour créer la messagerie d'un nouvel employé depuis votre intranet.

Il y a deux façons de l'utiliser :

• Depuis le compte lui-même, en SSH, avec la commande uapi. Aucune authentification supplémentaire n'est demandée.
• Depuis l'extérieur, avec des appels HTTPS au port 2083 de cPanel authentifiés par un jeton.

Tous les appels suivent le même schéma : un module (Email, Mime, Ftp…), une fonction (list_pops, add_redirect…) et ses paramètres. Cherchez la fonction dont vous avez besoin dans la documentation d'UAPI et adaptez n'importe quel exemple de cet article.

Utiliser l'API en SSH avec la commande uapi

Si l'automatisation s'exécute sur l'hébergement lui-même (un script, une tâche cron), connectez-vous en SSH et utilisez la commande uapi. Elle agit toujours sur votre compte, avec votre utilisateur.

Créer une redirection

Pour rediriger dominio1.com vers https://dominio2.com avec une redirection permanente (301), utilisez la fonction Mime add_redirect :

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

• domain : le domaine à rediriger.
• redirect : l'adresse de destination.
• type : permanent (301) ou temp (302). Pendant vos tests, utilisez temp : les navigateurs mémorisent les 301 et il devient ensuite difficile de voir les changements.
• redirect_www : 0 redirige avec et sans www ; 1 seulement avec www ; 2 seulement sans www.

La réponse indique si la redirection a été créée. Vérifiez status: 1 et que errors est vide.

Avec --output=, vous choisissez le format de la réponse : json, jsonpretty ou yaml (la valeur par défaut).

Lister les comptes de messagerie

La fonction Email list_pops renvoie tous les comptes de messagerie :

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: ~

Pour ne garder que les adresses, une par ligne :

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

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

Si vous préférez travailler en JSON, jq le fait de façon plus fiable :

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

Pour enregistrer la liste dans un fichier, ajoutez > correos.txt à la fin de la commande. Si le fichier existe, il est écrasé.

La commande uapi fonctionne en SSH et dans les tâches cron. Pas depuis PHP : sur notre hébergement, les fonctions qui exécutent des commandes (exec, shell_exec, system…) sont désactivées par sécurité. Si vous avez besoin de l'API depuis un script PHP, même sur le même hébergement, appelez-la en HTTPS avec un jeton, comme expliqué ci-dessous.

Utiliser l'API depuis un autre serveur avec un jeton

Créer le jeton

Dans cPanel, allez dans Sécurité > Manage API Tokens (gérer les jetons d'API) et cliquez sur Créer. Donnez-lui un nom qui identifie l'intégration et, s'il s'agit d'un usage temporaire, une date d'expiration.

cPanel n'affichera le jeton qu'une seule fois : copiez-le et conservez-le en lieu sûr. Quiconque possède le jeton peut tout faire sur votre compte : ne le placez donc ni dans du code public ni dans des fichiers à l'intérieur de public_html. S'il n'est plus utilisé ou si vous pensez qu'il a fuité, révoquez-le depuis le même écran.

Faire des appels avec cURL

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

• USUARIO : votre utilisateur cPanel.
• TOKEN : le jeton que vous avez créé.
• tudominio.com : n'importe quel domaine de votre compte qui pointe vers l'hébergement et dont le certificat SSL est actif. Le nom du serveur fonctionne aussi.

L'adresse suit toujours le format execute/Modulo/funcion?parametro=valor. Si vous avez besoin de plusieurs paramètres, séparez-les par &.

Par exemple, pour lister les comptes de messagerie :

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

La réponse arrive en JSON. Vérifiez status (qui doit valoir 1) et errors : une réponse HTTP 200 peut contenir une erreur de l'API.

Vider le dossier spam

La fonction SpamAssassin clear_spam_box vide le dossier spam de tous les comptes de messagerie de votre hébergement :

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

Pour tester des appels sans écrire de code, un client REST comme Insomnia ou Postman est pratique.

Le même appel en PHP avec 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";

Ne désactivez pas la vérification SSL (CURLOPT_SSL_VERIFYPEER) : en cas d'erreur de certificat, utilisez un domaine avec un SSL valide ou le nom du serveur.

Appels depuis Laravel

Si vous utilisez Laravel ou n'importe quel projet avec Composer, le client HTTP (ou Guzzle) simplifie les appels. Enregistrez les données dans le .env et lisez-les depuis config/services.php :

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

Vider le spam :

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 en cas de succès

Lister les comptes FTP

Avec Ftp list_ftp, seule l'adresse change :

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

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

Créer un compte de messagerie

La fonction Email add_pop crée une boîte mail. Elle a besoin au minimum de l'adresse et du mot de passe ; avec quota, vous fixez la taille en Mo (0 signifie illimité). Envoyez les données en POST pour que le mot de passe n'apparaisse ni dans l'URL ni dans les journaux du serveur :

$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') ?? []));
}

Si le mot de passe est faible, cPanel refuse le compte et l'explique dans errors.

Avec ces éléments, vous pouvez enchaîner les appels et construire des flux complets : arrivée d'employés, nettoyage périodique, rapports… Si un appel qui modifie des données est interrompu par un délai d'attente, vérifiez l'état avant de le relancer : il a pu être appliqué malgré tout.