Desarrollando y automatizando vía API de cPanel

La UAPI de cPanel permite consultar y modificar funciones de una cuenta. Las operaciones disponibles dependen de la versión, los permisos y los servicios habilitados; no concede acceso administrativo a todo el servidor.

Empieza con una consulta de lectura y comprueba la respuesta antes de automatizar altas, cambios o borrados.

Desde SSH en la propia cuenta

El comando local utiliza la identidad del usuario con el que has iniciado sesión. No pide un token adicional, pero el acceso ya está autenticado por SSH y limitado a esa cuenta.

Para consultar los buzones:

/usr/local/cpanel/bin/uapi --output=jsonpretty Email list_pops

Revisa result.status y result.errors: obtener una respuesta no significa que la operación haya terminado correctamente. La salida del comando incluye un contenedor result; la respuesta HTTP de UAPI presenta esos datos directamente.

Si necesitas procesar el listado, utiliza un lector JSON en lugar de filtrar texto con grep o sed. Por ejemplo, con jq instalado:

/usr/local/cpanel/bin/uapi --output=json Email list_pops \
  | jq -er 'if .result.status == 1 then .result.data[]?.email else error("UAPI no ha completado la consulta") end'

El listado puede contener direcciones privadas. Si lo guardas, hazlo fuera de la raíz pública y con permisos adecuados; > sobrescribe un archivo existente.

Desde un sistema externo

Crea un token en cPanel > Manage API Tokens, exclusivo para la integración y con caducidad. Trátalo como una credencial de la cuenta: no asumas que solo permite una operación porque lo hayas creado para ella. Revócalo cuando deje de utilizarse.

Usa el nombre seguro del servidor de cPanel, con certificado válido y puerto 2083. No sirve cualquier dominio si apunta a otro destino o su certificado no cubre ese nombre.

Guarda la cabecera en un archivo privado, por ejemplo ~/.config/cpanel-api/curl.conf, fuera de la web y con permisos 0600. Su contenido tiene este formato; sustituye los marcadores mediante tu gestor de secretos:

header = "Authorization: cpanel USUARIO_CPANEL:TOKEN"

La consulta no necesita incluir el token en la línea de comandos:

curl --fail --silent --show-error --max-time 30 \
  --config "$HOME/.config/cpanel-api/curl.conf" \
  'https://servidor.example:2083/execute/Email/list_pops'

No desactives la verificación TLS para resolver un error de certificado. Comprueba también status y errors en el JSON: una respuesta HTTP 200 puede contener un fallo de UAPI.

Consultar cuentas FTP desde PHP y Laravel

En una aplicación Laravel, obtén los datos desde su configuración protegida. El ejemplo usa el cliente HTTP del framework y valida transporte y resultado:

use Illuminate\Support\Facades\Http;

$server = config('services.cpanel.server');
$username = config('services.cpanel.username');
$token = config('services.cpanel.token');

if (!$server || !$username || !$token) {
    throw new RuntimeException('Falta la configuración de cPanel.');
}

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

$data = $response->json();
if ((int) ($data['status'] ?? 0) !== 1) {
    throw new RuntimeException('cPanel no ha completado la consulta.');
}

$accounts = $data['data'] ?? [];

Configura server como hostname, sin esquema ni ruta, y no lo tomes de una entrada libre de visitantes. No registres tokens, contraseñas ni respuestas completas con datos de clientes. En PHP sin framework, aplica las mismas comprobaciones con cURL o una biblioteca HTTP.

Operaciones que cambian datos

Antes de programar una escritura, consulta los parámetros y consecuencias de su función en la documentación de UAPI.

• Redirecciones: Mime/add_redirect permite crearlas. Prueba con un dominio de desarrollo y tipo temporal; revisa origen, destino, www y conservación de rutas antes de usar una redirección permanente.
• Crear correo: revisa UserManager/create_user para nuevas integraciones. Si mantienes código con Email/add_pop, comprueba su compatibilidad y envía contraseñas mediante POST, nunca en la URL.
• Vaciar spam: SpamAssassin/clear_spam_box afecta al spam de todas las direcciones de la cuenta, incluida la principal. No es una prueba de conectividad ni una limpieza limitada a un buzón.

Comprueba el estado después de una escritura. Si se agota el tiempo de espera, no repitas automáticamente: la operación podría haberse aplicado aunque tu programa no recibiera la respuesta. Diseña cada automatización para detectar resultados existentes y conservar un registro sin secretos.