API do painel: guia de integração

1. O que é a API do painel

A API permite que um sistema da sua empresa faça, de forma automática, as mesmas tarefas que você faz no painel: consultar domínios e caixas, criar caixas, trocar senhas por link seguro, cuidar de apelidos, encaminhamentos e registros DNS, consultar os logs de e-mail e acompanhar o histórico do suporte.

Cada chamada é feita em nome de um usuário do painel e só chega ao que esse usuário vê na tela: os domínios da sua empresa, ou do time dele, e as ações que o papel dele permite. As regras da tela também valem na API. Usuários com o papel Somente leitura ou Helpdesk só fazem consultas.

Exemplos de uso: criar a caixa de uma pessoa quando ela é cadastrada no sistema de RH, desativar a caixa quando ela sai, conferir periodicamente o DNS do domínio ou consultar por que uma mensagem não chegou.

• Endereço da API: https://painel.lua.email/api/v1. O formato das respostas e dos pedidos é JSON, em UTF-8, sempre por HTTPS.
• Operações: a lista completa, por área e com exemplos, está em API do painel: operações e exemplos.

2. Antes de começar

1. Você precisa de um usuário do painel com o papel Administrador: a aba Token de API só aparece para esse papel. Quem gerencia os usuários da empresa também cria e revoga tokens de outra pessoa, no menu Usuários, ao editar o usuário.
2. Escolha onde o sistema vai guardar o token, por exemplo em uma variável de ambiente ou em um cofre de senhas. Trate o token como uma senha.
3. Decida o que a integração vai fazer, para marcar só as permissões necessárias.

3. Criar o token

O token é a chave que identifica o seu sistema em cada chamada. Ele só é criado na tela do painel. A API não cria tokens, de propósito: assim, um token exposto não consegue gerar outros.

1. No painel, abra Meu perfil, no menu do seu usuário, no canto superior direito, e escolha a aba Token de API.
2. Em Criar um token novo, informe um nome que identifique a integração, por exemplo "Sistema de RH". O nome pode ter até 80 caracteres e serve para reconhecer o token na lista. Se ficar em branco, o token recebe o nome "Token de API".
3. Em Permissões do token (escopos), escolha somente o que a integração precisa. A opção Todas as permissões do perfil do usuário vem marcada; desmarque-a para escolher as permissões uma a uma.
4. Escolha a Validade, de 30 dias a 2 anos, e clique em Criar token.
5. Clique em Copiar e guarde o token em local seguro. Por segurança, ele é mostrado uma única vez.

• Cada usuário pode ter até 10 tokens ativos ao mesmo tempo, um para cada integração. Criar um token novo não desativa os outros.
• Ao criar um token, o dono recebe um aviso por e-mail e na central de notificações.
• A lista mostra o nome, o início do token (só para reconhecê-lo), as permissões, a validade e o último uso de cada um.

4. Permissões do token

Cada token pode ser limitado a algumas áreas do painel. A permissão nunca amplia o que o usuário pode fazer: em toda chamada, o painel confere se o item pertence a um domínio ao qual o usuário tem acesso.

• Uma consulta (método GET) é aceita com a permissão Leitura ou com a permissão da área. Criar, alterar e remover exigem a permissão da área.
• Um token com Todas as permissões do perfil do usuário vale para tudo o que o perfil permite.
• Usuários com o papel Somente leitura só podem ter tokens com a permissão Leitura.
• Sem a permissão exigida, a resposta é 403 com o código escopo_insuficiente.

5. Validade e revogação

• Validade: 30, 90, 180, 365 (padrão) ou 730 dias. O máximo é de 2 anos. Depois do vencimento, as chamadas são recusadas (401 token_invalido) e é preciso criar outro token.
• Revogar: na lista, clique em Revogar e confirme. O token deixa de funcionar na chamada seguinte, e os outros continuam valendo. Pela API, use DELETE /api/v1/tokens/{token_id} para revogar um dos seus tokens ou DELETE /api/v1/token para revogar o token que faz a chamada.
• Trocar a senha do usuário ou desativá-lo revoga na hora todos os tokens dele.
• Se suspeitar que um token foi exposto, revogue-o e crie outro.

6. Primeira chamada

Para conferir se o token funciona, consulte os dados do próprio token. Guarde o valor em uma variável de ambiente chamada LUA_TOKEN, sem colá-lo nos comandos. No terminal, o comando read pede o token sem mostrá-lo na tela: cole o token e tecle Enter.

read -rs LUA_TOKEN && export LUA_TOKEN
curl -H "Authorization: Bearer $LUA_TOKEN" https://painel.lua.email/api/v1/token

import os
import requests

response = requests.get(
    "https://painel.lua.email/api/v1/token",
    headers={"Authorization": "Bearer " + os.environ["LUA_TOKEN"]},
    timeout=30,
)
print(response.json())

A resposta mostra o usuário, o perfil, as permissões e a validade do token. O token em si nunca volta na resposta.

{
  "success": true,
  "data": {
    "username": "maria@suaempresa.com.br",
    "perfil": "cliente",
    "escopos": ["caixas", "leitura"],
    "escopos_restritos": true,
    "valido_ate": "2027-11-10T00:00:00",
    "id": 12,
    "nome": "Sistema de RH",
    "prefixo": "a1b2c3d4"
  }
}

7. Como a API responde

Em caso de sucesso, a resposta traz success verdadeiro e os dados em data. As listas trazem também a paginação: o padrão é de 25 itens por página e o máximo, de 100. Para as páginas seguintes, envie os parâmetros page (número da página) e per_page (itens por página).

{
  "success": true,
  "data": [ ],
  "pagination": {"page": 1, "per_page": 25, "total": 120, "total_pages": 5}
}

Em caso de erro, a resposta traz success falso, um texto em message e, no objeto erro, o codigo, que é estável e serve para o seu sistema decidir o que fazer, e a mensagem, escrita para a pessoa.

{
  "success": false,
  "error": "Forbidden",
  "message": "Este token não tem o escopo necessário para esta operação.",
  "erro": {"codigo": "escopo_insuficiente", "mensagem": "Este token não tem o escopo necessário para esta operação."}
}

Um item de outro cliente responde como se não existisse (404). Algumas operações mais antigas ainda respondem parte dos erros só com success e error. Por isso, trate cada erro pelo código HTTP e, quando houver, por erro.codigo.

8. Limites de uso

Ao receber 429, espere os segundos indicados no cabeçalho Retry-After antes de repetir a chamada.

9. Erros e o que fazer

Os códigos 200, 201 e 202 indicam sucesso. O 201 indica que o item foi criado; o 202, que o pedido foi aceito e será executado em seguida, como ao apagar um aparelho a distância ou pedir um domínio novo.

10. Cuidados ao usar a API

• As chamadas são reais. Criar, alterar e remover pela API mudam os dados dos seus domínios na hora, e nem tudo pode ser desfeito pela API, como a remoção de uma caixa. Para experimentar, prefira as consultas.
• Um token para cada integração, com nome claro e só as permissões necessárias. Revogue os que não usa mais.
• Senhas de caixa nunca aparecem na resposta. O painel entrega um link seguro, que expira, para você repassar à pessoa. Se o gerador do link não responder, nada é alterado.
• O que foi bloqueado por pendência financeira, por exemplo uma assinatura em atraso, não é reativado pela API nem pela tela. O desbloqueio acontece com a regularização da assinatura. Desativar continua permitido.
• Ações que removem ou trocam dados pedem uma confirmação explícita no corpo do pedido, com o valor true, em um campo como confirmo_remocao, confirmo_troca ou confirmo. No painel, em Suporte > API: documentação e teste, cada operação mostra o seu campo.
• Toda alteração fica registrada com o usuário dono do token, a data e a hora. Os cabeçalhos opcionais X-Lua-Chamado e X-Lua-Motivo acrescentam ao registro o número do chamado e o motivo.
• Em DNS, envie a versão da zona recebida na consulta (zone_version). Se a resposta for 409, consulte de novo antes de repetir. Com o cabeçalho Idempotency-Key, repetir a mesma chamada não aplica a alteração duas vezes.

11. Skill para o Claude e outras IAs

A skill ensina um assistente de IA a usar a API do painel com segurança: montar a chamada certa, escolher a permissão, tratar os erros e pedir a sua confirmação antes de alterar qualquer dado.

• Baixar a skill para o Claude (lua-painel-api.zip). Dentro do arquivo estão o SKILL.md e um pequeno programa de apoio, scripts/lua_api.py.
• Ver o SKILL.md, para colar em outra ferramenta de IA que aceite instruções em texto.
• Sem baixar nada: peça ao assistente que leia https://lua.email/docs-api.md e https://lua.email/docs-api-operacoes.md. As duas páginas têm tudo de que ele precisa.

Como instalar

1. No Claude, abra as configurações de skills e envie o arquivo lua-painel-api.zip. Em outras ferramentas, copie a pasta lua-painel-api para a pasta de skills indicada por elas.
2. Crie o token no painel, com as permissões que a tarefa exige, e guarde-o na variável de ambiente LUA_TOKEN do computador onde o assistente trabalha. Não cole o token na conversa.
3. Peça a tarefa em linguagem natural.

Exemplo de uso

Pedido: "Liste as caixas do domínio suaempresa.com.br." O assistente encontra a operação, confere que ela exige a permissão Leitura ou Caixas de e-mail e monta a chamada:

curl -H "Authorization: Bearer $LUA_TOKEN" \
  "https://painel.lua.email/api/v1/domains/suaempresa.com.br/mailboxes?per_page=100"

Depois da resposta, ele apresenta o resultado em uma tabela com o endereço, o nome e a situação de cada caixa. Se houver mais de uma página, pede as seguintes. Antes de criar, alterar ou remover algo, ele descreve o que vai fazer e espera a sua confirmação.

12. Onde conhecer mais e como pedir ajuda

• No painel, em Suporte > API: documentação e teste (endereço https://painel.lua.email/api-docs/), cada operação aparece com os campos, a permissão exigida e o botão Try it out, que testa a chamada com o seu token. O mesmo atalho fica em Meu perfil, na aba Token de API. As chamadas feitas ali são reais: para experimentar, prefira as consultas.
• Os nomes das telas citados neste guia são os do painel: Meu perfil, Token de API, Criar um token novo, Criar token e Revogar.
• Em Suporte > Histórico do suporte, você acompanha o que a equipe fez nos seus domínios. O mesmo histórico pode ser consultado pela API, com a permissão Leitura.
• Dúvidas? Fale com o suporte.