Secções
Secções

Desenvolvimento e bases de dados

API do cPanel (UAPI): automatizar correio, FTP e redirecionamentos a partir de SSH, cURL ou PHP

Revisto a 10 min de leitura API do cPanel automatização

A API do cPanel (UAPI) dá acesso a quase todas as funções da sua conta: criar contas de correio, redirecionamentos, cópias de segurança, consultar estatísticas… Com ela pode automatizar tarefas repetitivas ou ligar o cPanel às suas próprias ferramentas, por exemplo para criar o correio de um novo funcionário a partir da sua intranet.

Há duas formas de a usar:

  • A partir da própria conta, por SSH, com o comando uapi. Não pede nenhuma autenticação adicional.
  • A partir do exterior, com chamadas HTTPS à porta 2083 do cPanel autenticadas com um token.

Todas as chamadas seguem o mesmo esquema: um módulo (Email, Mime, Ftp…), uma função (list_pops, add_redirect…) e os seus parâmetros. Procure a função de que precisa na documentação da UAPI e adapte qualquer um dos exemplos deste artigo.

Usar a API por SSH com o comando uapi

Se a automatização for executada no próprio alojamento (um script, uma tarefa cron), entre por SSH e use o comando uapi. Atua sempre sobre a sua conta, com o seu utilizador.

Criar um redirecionamento

Para redirecionar dominio1.com para https://dominio2.com com um redirecionamento permanente (301), use a função Mime add_redirect:

uapi --output=jsonpretty \
  Mime \
  add_redirect \
  domain='dominio1.com' \
  redirect='https://dominio2.com/' \
  redirect_www=0 \
  type='permanent'
  • domain: o domínio que quer redirecionar.
  • redirect: o endereço de destino.
  • type: permanent (301) ou temp (302). Se estiver a testar, use temp: os navegadores guardam os 301 e depois custa ver as alterações.
  • redirect_www: 0 redireciona com e sem www; 1 só com www; 2 só sem www.

A resposta indica se foi criado. Repare em status: 1 e em que errors esteja vazio.

Com --output= escolhe o formato da resposta: json, jsonpretty ou yaml (o valor predefinido).

Listar as contas de correio

A função Email list_pops devolve todas as contas de correio:

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

Para ficar apenas com os endereços, um por linha:

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

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

Se preferir trabalhar com JSON, o jq fá-lo de forma mais fiável:

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

Para guardar a lista num ficheiro, acrescente > correos.txt no fim do comando. Se o ficheiro existir, é substituído.

O comando uapi funciona por SSH e em tarefas cron. A partir do PHP não: no nosso alojamento, as funções que executam comandos (exec, shell_exec, system…) estão desativadas por segurança. Se precisar da API a partir de um script PHP, mesmo que esteja no mesmo alojamento, chame-a por HTTPS com um token, como se explica a seguir.

Usar a API a partir de outro servidor com um token

Criar o token

No cPanel, entre em Security > Manage API Tokens e clique em Create. Dê-lhe um nome que identifique a integração e, se for para algo temporário, uma data de expiração.

Criar um token de API no cPanel

O cPanel mostra-lhe o token uma única vez: copie-o e guarde-o num local seguro. Quem tiver o token pode fazer qualquer coisa na sua conta, por isso não o coloque em código público nem em ficheiros dentro de public_html. Se deixar de ser usado ou se achar que foi divulgado, revogue-o a partir do mesmo ecrã.

Fazer chamadas com cURL

curl -H 'Authorization: cpanel USUARIO:TOKEN' \
  'https://tudominio.com:2083/execute/Modulo/funcion?parametro=valor'
  • USUARIO: o seu utilizador do cPanel.
  • TOKEN: o token que criou.
  • tudominio.com: qualquer domínio da sua conta que aponte para o alojamento e tenha o certificado SSL ativo. Também serve o nome do servidor.

O endereço segue sempre o formato execute/Modulo/funcion?parametro=valor. Se precisar de vários parâmetros, separe-os com &.

Por exemplo, para listar as contas de correio:

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

A resposta chega em JSON. Verifique status (deve ser 1) e errors: uma resposta HTTP 200 pode trazer um erro da API.

Esvaziar a pasta de spam

A função SpamAssassin clear_spam_box esvazia a pasta de spam de todas as contas de correio do seu alojamento:

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

Para testar chamadas sem escrever código, é prático um cliente REST como o Insomnia ou o Postman.

A mesma chamada em PHP com 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";

Não desative a verificação SSL (CURLOPT_SSL_VERIFYPEER): se der erro de certificado, use um domínio com SSL válido ou o nome do servidor.

Chamadas a partir do Laravel

Se usar o Laravel ou qualquer projeto com Composer, o cliente HTTP (ou o Guzzle) simplifica as chamadas. Guarde os dados no .env e leia-os a partir de config/services.php:

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

Esvaziar o 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 se correu bem

Listar as contas FTP

Com Ftp list_ftp só muda o endereço:

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

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

Criar uma conta de correio

A função Email add_pop cria uma caixa de correio. Precisa, pelo menos, do endereço e da palavra-passe; com quota define o tamanho em MB (0 é ilimitado). Envie os dados por POST para que a palavra-passe não fique no URL nem nos registos do servidor:

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

Se a palavra-passe for fraca, o cPanel rejeita a conta e explica-o em errors.

Com estas peças pode encadear chamadas e montar fluxos completos: criação de contas de funcionários, limpeza periódica, relatórios… Se uma chamada que modifica dados for interrompida por tempo de espera esgotado, verifique o estado antes de a repetir: pode ter sido aplicada na mesma.

Também lhe pode ser útil

Algo não bate certo ou mudou? Diga-nos e revemos.