---
name: lua-painel-api
description: Usa a API do painel do lua.email para consultar e administrar domínios, caixas de e-mail, listas de e-mail (aliases), DNS, remetentes permitidos e bloqueados e logs de e-mail, no perfil cliente. Use quando a pessoa pedir para listar caixas ou domínios, criar, ativar ou desativar caixa, trocar senha por link seguro, conferir o DNS ou consultar por que uma mensagem não chegou, pela API ou por automação.
---

# API do painel do lua.email (perfil cliente)

A API faz, de forma automática, o que o painel faz na tela, em nome do usuário dono do token e só nos domínios da empresa dele. Endereço: `https://painel.lua.email/api/v1`. Formato: JSON em UTF-8, sempre por HTTPS.

Documentação completa e atual (leia quando precisar de campos ou exemplos): https://lua.email/docs-api.md (guia) e https://lua.email/docs-api-operacoes.md (operações com exemplos em curl e Python).

## Regras de segurança (valem sempre)

1. O token vem da variável de ambiente `LUA_TOKEN`. **Nunca peça o token, a senha, o código de verificação em duas etapas nem um link de senha na conversa**, e não os mostre, grave ou repita. Se a variável não existir, explique o caminho: no painel, abrir Meu perfil (menu do usuário, no canto superior direito) e a aba Token de API; em Criar um token novo, escolher só as permissões necessárias e a validade e clicar em Criar token; copiar o token, que é mostrado uma única vez, e guardá-lo na variável `LUA_TOKEN` do computador, fora da conversa.
2. Se a pessoa colar um token ou uma senha na conversa, não use o valor: avise que ele ficou exposto e oriente a revogar o token (Meu perfil, Token de API) ou trocar a senha. Para criar uma caixa, não receba a senha pela conversa: sugira criar a caixa na tela do painel ou, pela API, usar a troca de senha por link seguro logo depois de criá-la, para que a pessoa receba a senha definitiva pelo link.
3. Consultas (GET) podem rodar direto. **Antes de criar, alterar ou remover qualquer coisa**, descreva o que será feito (domínio, caixa e valores) e espere a confirmação da pessoa. Remoções e desativações pedem confirmação explícita.
4. As chamadas são reais e não há como desfazer pela API. Na dúvida, consulte primeiro.
5. Senhas nunca voltam na resposta: a troca de senha devolve só um link seguro que expira. Entregue o link à pessoa, nunca invente nem peça senha.
6. O que está bloqueado por pendência financeira (409 `bloqueado_pelo_billing`) não é reativado pela API. Não tente de novo nem contorne: explique que o desbloqueio acontece com a regularização da assinatura e oriente a pessoa a falar com o financeiro ou com o suporte (https://lua.email/suporte). Ativar também pede confirmação, como criar, alterar, remover e desativar.
7. Só use as operações listadas abaixo. Não invente endereços.

## Como chamar

Cabeçalho em toda chamada, exceto `/health`: `Authorization: Bearer $LUA_TOKEN`. Pedidos com corpo levam `Content-Type: application/json`. Use o programa de apoio (`scripts/lua_api.py`, dentro da pasta desta skill; use o caminho completo se não estiver nela), que lê o token da variável, repete a chamada se o painel pedir uma pausa (429) e só envia alterações com `--confirmo`:

```
python3 scripts/lua_api.py GET /domains
python3 scripts/lua_api.py GET /domains/suaempresa.com.br/mailboxes --param per_page=100
python3 scripts/lua_api.py POST /domains/suaempresa.com.br/aliases --confirmo \
  --json '{"address_local": "contato", "goto": ["maria@suaempresa.com.br"]}'
```

Ou com curl:

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

## Respostas, páginas e erros

- Sucesso: `{"success": true, "data": ...}`. Listas trazem `pagination` (`page`, `per_page`, `total`, `total_pages`): padrão de 25 itens por página, máximo de 100. Continue pedindo `page` enquanto houver páginas.
- Erro: `{"success": false, "error", "message", "erro": {"codigo", "mensagem"}}`. Decida pelo código HTTP e por `erro.codigo`; mostre à pessoa a `mensagem`.
- Item de outro cliente responde 404, igual ao que não existe.
- Limite: 600 chamadas por minuto por usuário, somando todos os tokens dele. Em 429, espere os segundos do cabeçalho `Retry-After`.
- Logs: janela de até 7 dias por chamada, dentro dos últimos 180 dias. DNS: 30 alterações por minuto em cada domínio, de 1 a 50 por pedido.
- Cabeçalhos opcionais em alterações: `X-Lua-Chamado` (número do chamado) e `X-Lua-Motivo` (motivo, até 500 caracteres), que vão para o registro de ações.

## Permissões do token (Meu perfil, Token de API)

- **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.

Consulta (GET) passa com **Leitura** ou com a permissão da área; criar, alterar e remover exigem a permissão da área. O token nunca pode mais do que o usuário pode no painel.

## Erros frequentes

- 400: Campo errado ou ausente, ou falta a confirmação exigida. Corrija o pedido conforme a mensagem e a lista `erros`.
- 401: `token_invalido`: o token não existe, venceu ou foi revogado. Peça à pessoa que crie um token novo no painel.
- 403: Falta a permissão (`escopo_insuficiente`), o usuário tem o papel Somente leitura ou Helpdesk e só consulta (`papel_so_consulta`) ou o domínio não é da empresa (`dominio_sem_acesso`).
- 404: O item não existe ou é de outro cliente (`caixa_nao_encontrada`, `dominio_nao_encontrado`).
- 409: `bloqueado_pelo_billing` (não repita), `caixa_sem_licenca` (atribua a licença antes), `zone_changed` ou `plano_mudou` (consulte o DNS de novo) e `dns_fora_da_edgium` (o DNS do domínio não está ativo na Edgium).
- 422: O painel recusou o valor pelas mesmas regras da tela; leia a lista `erros`.
- 429: `limite_de_chamadas`: aguarde os segundos indicados em `Retry-After`.
- 503: Um serviço de apoio não respondeu (`link_indisponivel`, `logs_indisponiveis`). Nada foi alterado, salvo quando a resposta disser o contrário (no DNS, veja `pode_ter_mudado`). Aguarde alguns minutos e repita.

## Operações do perfil cliente

Nos caminhos, troque o que está entre chaves pelo valor real (o domínio, o endereço completo da caixa etc.). Todos começam com `/api/v1`.

### Verificação, token e histórico do suporte

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /health` | Qualquer token | Verifica se a API está funcionando. Não precisa de token. |
| `GET /token` | Qualquer token | Mostra o usuário, as permissões e a validade do token que fez a chamada. |
| `DELETE /token` | Qualquer token | Revoga o token que fez a chamada. |
| `GET /tokens` | Qualquer token | Lista os seus tokens, sem o valor. |
| `DELETE /tokens/{token_id}` | Qualquer token | Revoga um dos seus tokens. |
| `GET /support-history` | Leitura | Consulta o histórico do suporte: o que a equipe de atendimento e as integrações fizeram nos seus domínios. |

### Domínios

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains` | Leitura | Lista os seus domínios. |
| `GET /domains/{domain}` | Leitura | Consulta um domínio. |
| `POST /domains` | Suporte | Pede um domínio novo, que fica pendente até o registro TXT ser conferido no DNS. |
| `GET /domain-requests/{request_id}` | Leitura | Consulta um pedido de domínio. |

### Caixas de e-mail

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains/{domain}/mailboxes` | Caixas de e-mail | Lista as caixas de um domínio. |
| `POST /domains/{domain}/mailboxes` | Caixas de e-mail | Cria uma caixa. |
| `GET /mailboxes/{mailbox}` | Caixas de e-mail | Consulta uma caixa. |
| `PUT /mailboxes/{mailbox}` | Caixas de e-mail | Altera uma caixa. |
| `DELETE /mailboxes/{mailbox}` | Caixas de e-mail | Remove uma caixa, com as regras de remoção do painel. |
| `PUT /mailboxes/{mailbox}/active` | Caixas de e-mail | Ativa ou desativa uma caixa. |
| `POST /mailboxes/{mailbox}/license` | Caixas de e-mail | Atribui uma licença a uma caixa sem licença. |
| `POST /mailboxes/{mailbox}/password` | Caixas de e-mail | Troca a senha da caixa e devolve um link seguro com a senha nova. |
| `PUT /mailboxes/{mailbox}/2fa` | Caixas de e-mail | Liga ou desliga a verificação em duas etapas (2FA) da caixa. |
| `GET /mailboxes/{mailbox}/quota` | Leitura | Mostra o uso do espaço da caixa e o plano atual. |
| `GET /mailboxes/{mailbox}/removal` | Caixas de e-mail | Mostra a situação do pedido de remoção da caixa. |
| `POST /mailboxes/{mailbox}/removal` | Caixas de e-mail | Coloca a caixa na fila de remoção, como o botão Remover da tela. O pedido pode ser cancelado no painel enquanto estiver pendente. |

### Ajustes de cada caixa

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /mailboxes/{mailbox}/forwarding` | Leitura | Consulta os endereços que recebem cópia das mensagens da caixa (encaminhamento). |
| `PUT /mailboxes/{mailbox}/forwarding` | Caixas de e-mail | Grava a lista completa de endereços que recebem cópia das mensagens da caixa (encaminhamento). |
| `GET /mailboxes/{mailbox}/aliases` | Leitura | Lista os apelidos que apontam para a caixa. |
| `POST /mailboxes/{mailbox}/aliases` | Caixas de e-mail | Inclui um apelido na caixa. |
| `DELETE /mailboxes/{mailbox}/aliases/{nickname}` | Caixas de e-mail | Retira um apelido da caixa. |
| `GET /mailboxes/{mailbox}/license-swap/candidates` | Leitura | Lista as caixas com as quais esta pode trocar de plano. |
| `GET /mailboxes/{mailbox}/license-swap/preview` | Leitura | Mostra a prévia da troca de plano entre duas caixas. |
| `POST /mailboxes/{mailbox}/license-swap` | Caixas de e-mail | Troca o plano entre duas caixas. |
| `GET /mailboxes/{mailbox}/service-groups` | Caixas de e-mail | Lista os grupos de serviço da caixa. |
| `PUT /mailboxes/{mailbox}/service-groups/{group_id}` | Caixas de e-mail | Inclui a caixa em um grupo de serviço. |
| `DELETE /mailboxes/{mailbox}/service-groups/{group_id}` | Caixas de e-mail | Retira a caixa de um grupo de serviço. |
| `GET /mailboxes/{mailbox}/access-requirements` | Caixas de e-mail | Consulta as exigências de acesso da caixa. |
| `PUT /mailboxes/{mailbox}/access-requirements` | Caixas de e-mail | Altera as exigências de acesso da caixa. |
| `GET /mailboxes/{mailbox}/deleted-recovery` | Caixas de e-mail | Mostra se a caixa tem o recurso Recuperar mensagens apagadas e de onde ele vem. |
| `GET /mailboxes/{mailbox}/devices` | Caixas de e-mail | Lista os aparelhos de celular da caixa. |
| `POST /mailboxes/{mailbox}/devices/{device_id}/remove` | Caixas de e-mail | Tira um aparelho da sincronização, sem apagar nada nele. |
| `POST /mailboxes/{mailbox}/devices/{device_id}/wipe` | Caixas de e-mail | Pede que o aparelho seja apagado a distância, como o botão Apagar o aparelho. |

### Listas de e-mail (aliases)

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains/{domain}/aliases` | Listas e apelidos | Lista as listas de e-mail de um domínio. |
| `POST /domains/{domain}/aliases` | Listas e apelidos | Cria uma lista de e-mail. |
| `GET /aliases/{alias}` | Listas e apelidos | Consulta uma lista de e-mail. |
| `PUT /aliases/{alias}` | Listas e apelidos | Altera uma lista de e-mail. |
| `DELETE /aliases/{alias}` | Listas e apelidos | Remove uma lista de e-mail. |

### Remetentes permitidos e bloqueados, IP bloqueado e postmaster

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains/{domain}/listas/{list}` | Listas e apelidos | Mostra a lista de permitidos ({list} = branca) ou de bloqueados ({list} = negra) do domínio. |
| `POST /domains/{domain}/listas/{list}` | Listas e apelidos | Inclui um remetente na lista de permitidos ou de bloqueados do domínio. |
| `DELETE /domains/{domain}/listas/{list}/{entry_id}` | Listas e apelidos | Retira um remetente da lista de permitidos ou de bloqueados do domínio. |
| `GET /tools/ip/{ip}/bloqueio` | Listas e apelidos | Consulta se um IP está bloqueado. |
| `GET /tools/ip/liberacoes` | Listas e apelidos | Lista os IPs liberados por 24 horas. |
| `POST /tools/ip/liberacoes` | Listas e apelidos | Libera por 24 horas um IP que está bloqueado. |
| `DELETE /tools/ip/liberacoes/{ip}` | Listas e apelidos | Encerra a liberação de um IP antes do prazo. |
| `POST /postmaster/pedidos` | Listas e apelidos | Abre um pedido ao postmaster, por exemplo para retirar um IP de uma lista de bloqueio. |
| `GET /postmaster/pedidos/{protocol}` | Listas e apelidos | Consulta um pedido ao postmaster. |

### DNS, domínios alias e roteamento

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains/{domain}/dns` | DNS e roteamento | Consulta os registros DNS do domínio. |
| `GET /domains/{domain}/dns/expected` | DNS e roteamento | Consulta os registros de e-mail esperados e a conferência no DNS público. |
| `PATCH /domains/{domain}/dns/records` | DNS e roteamento | Cria, altera e apaga de 1 a 50 registros DNS em um único pedido: ou tudo é gravado, ou nada. |
| `POST /domains/{domain}/dns/email/previa` | DNS e roteamento | Mostra a prévia dos registros de e-mail, sem alterar nada. |
| `POST /domains/{domain}/dns/email/aplicar` | DNS e roteamento | Aplica os registros de e-mail no DNS. |
| `POST /domains/{domain}/dns/email/trocar-mx` | DNS e roteamento | Troca o MX para que os e-mails passem a chegar ao lua.email. |
| `POST /domains/{domain}/dns/email/desfazer` | DNS e roteamento | Desfaz a última ação de e-mail no DNS (aplicar os registros ou trocar o MX). |
| `GET /domains/{domain}/alias-domains` | DNS e roteamento | Lista os domínios alias de um domínio. |
| `POST /alias-domains` | DNS e roteamento | Cria um domínio alias. |
| `GET /alias-domains/{aliasdomain}` | DNS e roteamento | Consulta um domínio alias. |
| `PUT /alias-domains/{aliasdomain}` | DNS e roteamento | Altera um domínio alias. |
| `DELETE /alias-domains/{aliasdomain}` | DNS e roteamento | Remove um domínio alias. |
| `GET /domains/{domain}/email-transports` | DNS e roteamento | Lista os roteamentos por e-mail de um domínio (endereços entregues em outro sistema de e-mail). |
| `GET /email-transports/{transport_id}` | DNS e roteamento | Consulta um roteamento por e-mail. |

### Logs de e-mail

| Método e caminho | Permissão | O que faz |
|---|---|---|
| `GET /domains/{domain}/logs/mensagens` | Logs de e-mail | Consulta a entrega das mensagens do domínio e a análise do filtro de spam. |

## Receitas

- **Listar as caixas de um domínio:** `GET /domains/{domain}/mailboxes?per_page=100` (por padrão só as ativas; `active_only=false` inclui as inativas; `search` busca por parte do endereço ou do nome). Mostre endereço, nome e situação em tabela.
- **Criar uma caixa:** `POST /domains/{domain}/mailboxes` com `{"username", "password", "name", "x_client_license_id"}`. A senha precisa cumprir a política do painel. A licença precisa ser da empresa e ter vaga livre: o número `x_client_license_id` aparece nas caixas que já existem, em `GET /domains/{domain}/mailboxes`; se não souber qual usar, pergunte à pessoa. Uma caixa sem licença não pode ser ativada.
- **Trocar a senha:** `POST /mailboxes/{mailbox}/password` (corpo opcional). Entregue só `data.link.url`.
- **Desativar ou ativar:** `PUT /mailboxes/{mailbox}/active` com `{"enabled": false}` ou `true`; informe `X-Lua-Motivo`.
- **Criar lista de e-mail:** `POST /domains/{domain}/aliases` com `{"address_local": "contato", "goto": ["a@...", "b@..."]}`.
- **Permitir um remetente:** `POST /domains/{domain}/listas/branca` com `{"origem": "fornecedor@exemplo.com.br"}` (`negra` para bloquear).
- **Conferir o DNS de e-mail:** `GET /domains/{domain}/dns/expected`; para aplicar, `POST /domains/{domain}/dns/email/aplicar` com `{"plan_hash": data.esperados.hash, "versao": data.esperados.versao}`. Só funciona com o DNS ativo na Edgium (caso contrário, 409 `dns_fora_da_edgium`). A troca do MX exige os registros de e-mail já aplicados e `{"confirmo": true}`.
- **Por que a mensagem não chegou:** `GET /domains/{domain}/logs/mensagens?destinatario=...&desde=AAAA-MM-DD&ate=AAAA-MM-DD`; leia `status_texto`, `resumo` e `caminho`.

## Exemplo de uso

Pedido: "Liste as caixas do domínio suaempresa.com.br."

1. Confirmar que `LUA_TOKEN` existe (sem mostrar o valor). Se não existir, orientar como criá-lo, como acima.
2. Chamar `GET /domains/suaempresa.com.br/mailboxes?per_page=100`.
3. Responder com uma tabela (endereço, nome, ativa) e o total de `pagination.total`. Se `total_pages` for maior que 1, pedir as páginas seguintes.
4. Em 403 `escopo_insuficiente`, explicar que o token precisa da permissão Leitura ou Caixas de e-mail; em 403 `dominio_sem_acesso`, pedir para conferir o nome do domínio.