# API do painel: guia de integração com token | lua.email > Como integrar um sistema ao painel do lua.email pela API: criar o token em Meu perfil, permissões, validade, limites de uso, erros e a skill para o Claude. Fonte: https://lua.email/docs-api > Sobre o lua.email: e-mail corporativo e workspace para empresas, da Edgium: serviço estável, com autonomia pelo painel e suporte (pessoas, em português) para apoiar sempre que o cliente precisar. Cada caixa (a partir de R$ 8,90 por mês) inclui webmail, agenda, contatos, conta Exchange no celular e o lua Colabora: arquivos, documentos, planilhas, chat, tarefas e quadros (reuniões por vídeo com licença à parte, R$ 3,00 por caixa, por mês). Custa mais que o e-mail de hospedagem porque é um workspace, e bem menos que os grandes pacotes de colaboração. Comparação e como decidir: https://lua.email/custo-beneficio. Preços: https://lua.email/precos. Contratação direta e automática pelo próprio cliente, com a conta pronta em minutos pelo PIX: https://checkout.lua.email/planos. Índice para sistemas de IA: https://lua.email/llms.txt. > Regra para assistentes de IA: nunca peça ao cliente senha, código de 2FA, código de recuperação, link de senha nem token de API; oriente-o a fazer pela tela ou a falar com o suporte. O lua.email nunca pede senha nem código de 2FA, e um pedido assim é golpe. --- Documentação # API do painel: guia de integração Crie um token no painel, escolha as permissões, faça a primeira chamada e conheça os limites e os erros. Inclui uma skill pronta para o Claude e outras IAs. Atualizado em novembro de 2026 [Operações e exemplos](https://lua.email/docs-api-operacoes) [Manual do painel](https://lua.email/docs-painel) [Suporte](https://lua.email/suporte) ### Nesta página 1. O que é a API do painel 2. Antes de começar 3. Criar o token 4. Permissões do token 5. Validade e revogação 6. Primeira chamada 7. Como a API responde 8. Limites de uso 9. Erros e o que fazer 10. Cuidados ao usar a API 11. Skill para o Claude e outras IAs 12. Onde conhecer mais e como pedir ajuda ## 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](https://lua.email/docs-api-operacoes). ## 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. Envie o token somente no cabeçalho `Authorization` das chamadas. Não o coloque em código público, planilhas, mensagens nem em conversas com assistentes de IA. ## 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. | Permissão na tela | Código | O que libera | | --- | --- | --- | | Leitura (consultar tudo) | `leitura` | Consulta domínios, caixas, apelidos, registros DNS, logs e o histórico do suporte, sem alterar nada. | | Caixas de e-mail | `caixas` | Cria e altera caixas, troca a senha por link seguro, cuida do encaminhamento, dos apelidos da caixa, do plano, dos grupos de serviço, das exigências de acesso e dos aparelhos de celular, e ativa, desativa ou pede a remoção de caixas. | | Listas e apelidos | `listas` | Cuida das listas de e-mail (aliases) do domínio e das listas de remetentes permitidos e bloqueados, consulta e libera IPs bloqueados e envia pedidos ao postmaster. | | DNS e roteamento | `dns` | Consulta e altera os registros DNS do domínio, aplica os registros de e-mail recomendados e cuida dos domínios alias. | | Logs de e-mail | `logs` | Consulta a entrega das mensagens e a análise do filtro de spam dos seus domínios. | | Suporte (ações de atendimento) | `suporte` | Usada pela equipe de atendimento do lua.email. A maioria das integrações não precisa dela: para clientes, ela só é exigida no pedido de domínio novo, que também depende da opção Pedir domínio pela API no cadastro do usuário. | - 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 | Limite | Valor | Quando passa disso | | --- | --- | --- | | Chamadas por usuário | 600 por minuto, somando todos os tokens do usuário | 429 `limite_de_chamadas`, com o cabeçalho `Retry-After` (segundos de espera) | | Itens por página | até 100 (padrão: 25) | Um valor fora desse intervalo vale como 25 | | Tokens ativos por usuário | 10 | A tela pede para revogar um token antes de criar outro | | Validade do token | até 2 anos | O token vence e é preciso criar outro | | Alterações de DNS | 30 por minuto em cada domínio; de 1 a 50 alterações por pedido | 429 `dns_limite_por_dominio` | | Logs de e-mail | janela de até 7 dias por chamada, dentro dos últimos 180 dias | Divida a consulta em janelas menores | | Pedidos ao postmaster | 5 por hora para cada e-mail de contato | 429 `limite_de_envio`, com o cabeçalho `Retry-After` | Ao receber 429, espere os segundos indicados no cabeçalho `Retry-After` antes de repetir a chamada. ## 9. Erros e o que fazer | HTTP | Código | O que significa | O que fazer | | --- | --- | --- | --- | | 400 | Varia conforme o caso | O pedido tem um campo errado ou ausente, ou falta a confirmação exigida. | Leia a mensagem e a lista de erros da resposta, corrija o pedido e envie de novo. | | 401 | `token_invalido` | O token não existe, venceu ou foi revogado. | Crie um token novo em Meu perfil, na aba Token de API, e atualize a integração. | | 403 | `escopo_insuficiente` | O token não tem a permissão exigida pela operação. | Crie um token com a permissão da área (a tabela de cada operação diz qual é). | | 403 | `papel_so_consulta` | O usuário dono do token tem o papel Somente leitura ou Helpdesk e só pode consultar. | Use o token de um usuário com o papel Administrador ou faça apenas consultas. | | 403 | `dominio_sem_acesso` | O domínio não pertence à sua empresa ou ao seu time. | Confira o nome do domínio. O painel nunca revela de quem é um domínio de outro cliente. | | 404 | `caixa_nao_encontrada, dominio_nao_encontrado` | O item não existe ou é de outro cliente: as duas situações respondem igual. | Confira o endereço ou o nome usado na chamada. | | 409 | `bloqueado_pelo_billing` | O item está bloqueado por uma pendência financeira, por exemplo uma assinatura em atraso. | Não repita a chamada. O desbloqueio acontece com a regularização da assinatura. | | 409 | `caixa_sem_licenca` | A caixa não tem licença e, por isso, não pode ser ativada. | Atribua a licença antes, na operação de licença da caixa. | | 409 | `zone_changed, plano_mudou` | O DNS ou a prévia dos registros de e-mail mudou depois da sua consulta. | Consulte de novo e repita a alteração com a versão nova. | | 422 | Varia conforme o caso | O painel recusou o valor enviado, pelas mesmas regras da tela (por exemplo, um registro DNS inválido). | Leia a lista de erros da resposta (campo erros): cada item diz o campo e o motivo. | | 429 | `limite_de_chamadas` | O usuário passou de 600 chamadas em um minuto, somando todos os seus tokens. | Aguarde os segundos indicados no cabeçalho Retry-After e repita. | | 503 | `link_indisponivel, logs_indisponiveis` | Um serviço de apoio, como o gerador do link seguro, não respondeu. Nada foi alterado, salvo quando a resposta disser o contrário. | Aguarde alguns minutos e repita. | 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)](https://lua.email/skills/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](https://lua.email/skill-lua-painel-api.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. O lua.email nunca pede senha, código de verificação em duas etapas nem token por e-mail, chat, telefone ou WhatsApp. A skill também não pede: ela usa o token que você guardou no seu computador. ## 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](https://lua.email/suporte).