# API do painel: operações com exemplos em curl | lua.email

> Todas as operações da API do painel para clientes, por área, com exemplos em curl e Python: domínios, caixas, listas, DNS, remetentes e logs de e-mail.

Fonte: https://lua.email/docs-api-operacoes
> 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: operações e exemplos

As operações da API do painel que o perfil cliente pode usar, por área, com a permissão de cada uma e exemplos em curl e Python.

Atualizado em novembro de 2026 [Guia de integração](https://lua.email/docs-api) [Manual do painel](https://lua.email/docs-painel) [Suporte](https://lua.email/suporte)

### Nesta página

1. Antes dos exemplos
2. Domínios
3. Caixas de e-mail
4. Listas de e-mail (aliases)
5. Remetentes, IP bloqueado e postmaster
6. DNS, domínios alias e roteamento
7. Logs de e-mail
8. Verificação, token e histórico do suporte

## 1. Antes dos exemplos

Todos os exemplos usam o token guardado na variável de ambiente `LUA_TOKEN` e o endereço `https://painel.lua.email/api/v1`. Para criar o token e conhecer as permissões, os limites e os erros, leia o [guia de integração](https://lua.email/docs-api).

Nos exemplos em Python, a função `call` abaixo envia a chamada e, se o painel pedir uma pausa (429), espera o tempo indicado e repete. Os demais exemplos em Python usam essa função.

```
import os
import time

import requests

BASE = "https://painel.lua.email/api/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["LUA_TOKEN"]}

def call(method, path, **options):
    while True:
        response = requests.request(method, BASE + path, headers=HEADERS, timeout=30, **options)
        if response.status_code != 429:
            return response
        time.sleep(int(response.headers.get("Retry-After", "5")))
```

Nos endereços, o que está entre chaves, como `{domain}` ou `{mailbox}`, deve ser trocado pelo domínio ou pelo endereço completo da caixa. Os exemplos usam o domínio fictício `suaempresa.com.br`.

Nas tabelas, a coluna **Permissão** mostra a permissão da área. Toda consulta (GET) também é aceita com a permissão **Leitura**; criar, alterar e remover exigem a permissão da área.

## 2. Domínios

Consulta os domínios da sua empresa ou do seu time, com a permissão **Leitura**. O pedido de domínio novo exige a permissão **Suporte** e a opção **Pedir domínio pela API** liberada no cadastro do usuário.

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

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

```
page = 1
while True:
    body = call("GET", "/domains", params={"page": page, "per_page": 100}).json()
    for domain in body["data"]:
        print(domain["domain"], domain["mailboxes"], "caixas")
    if page >= body["pagination"]["total_pages"]:
        break
    page += 1
```

## 3. Caixas de e-mail

Operações para listar, criar, ativar, desativar e remover caixas, trocar a senha e consultar o uso do espaço.

| Método | Endereço | Permissão | O que faz |
| --- | --- | --- | --- |
| `GET` | `/api/v1/domains/{domain}/mailboxes` | Caixas de e-mail | Lista as caixas de um domínio. |
| `POST` | `/api/v1/domains/{domain}/mailboxes` | Caixas de e-mail | Cria uma caixa. |
| `GET` | `/api/v1/mailboxes/{mailbox}` | Caixas de e-mail | Consulta uma caixa. |
| `PUT` | `/api/v1/mailboxes/{mailbox}` | Caixas de e-mail | Altera uma caixa. |
| `DELETE` | `/api/v1/mailboxes/{mailbox}` | Caixas de e-mail | Remove uma caixa, com as regras de remoção do painel. |
| `PUT` | `/api/v1/mailboxes/{mailbox}/active` | Caixas de e-mail | Ativa ou desativa uma caixa. |
| `POST` | `/api/v1/mailboxes/{mailbox}/license` | Caixas de e-mail | Atribui uma licença a uma caixa sem licença. |
| `POST` | `/api/v1/mailboxes/{mailbox}/password` | Caixas de e-mail | Troca a senha da caixa e devolve um link seguro com a senha nova. |
| `PUT` | `/api/v1/mailboxes/{mailbox}/2fa` | Caixas de e-mail | Liga ou desliga a verificação em duas etapas (2FA) da caixa. |
| `GET` | `/api/v1/mailboxes/{mailbox}/quota` | Leitura | Mostra o uso do espaço da caixa e o plano atual. |
| `GET` | `/api/v1/mailboxes/{mailbox}/removal` | Caixas de e-mail | Mostra a situação do pedido de remoção da caixa. |
| `POST` | `/api/v1/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. |

### Listar as caixas de um domínio

Por padrão, só as caixas ativas. Use `active_only=false` para incluir as inativas e `search` para buscar por parte do endereço ou do nome.

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

```
body = call("GET", "/domains/suaempresa.com.br/mailboxes", params={"per_page": 100}).json()
for mailbox in body["data"]:
    print(mailbox["username"], mailbox["name"], mailbox["active"])
```

```
{
  "success": true,
  "data": [
    {
      "id": 101,
      "username": "maria@suaempresa.com.br",
      "name": "Maria Souza",
      "domain": "suaempresa.com.br",
      "active": true,
      "quota": 10737418240,
      "x_client_license_id": 7,
      "created": "2026-03-01T08:00:00",
      "modified": "2026-09-02T16:30:00"
    }
  ],
  "pagination": {"page": 1, "per_page": 100, "total": 1, "total_pages": 1}
}
```

### Criar uma caixa

Exige a permissão **Caixas de e-mail**. A senha precisa atender à política de senhas do painel. A licença (`x_client_license_id`) define o plano e o espaço da caixa; ela precisa ser da sua empresa e ter vaga livre. O número da licença aparece no campo `x_client_license_id` das caixas que já existem. Uma caixa sem licença não pode ser ativada.

```
curl -X POST \
  -H "Authorization: Bearer $LUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username": "ana@suaempresa.com.br", "password": "Troque-Esta-Senha-9", "name": "Ana Lima", "x_client_license_id": 7}' \
  "https://painel.lua.email/api/v1/domains/suaempresa.com.br/mailboxes"
```

```
response = call("POST", "/domains/suaempresa.com.br/mailboxes", json={
    "username": "ana@suaempresa.com.br",
    "password": "Troque-Esta-Senha-9",
    "name": "Ana Lima",
    "x_client_license_id": 7,
})
print(response.status_code, response.json())
```

### Trocar a senha de uma caixa

O painel gera uma senha nova, troca a senha da caixa e devolve somente o endereço de um link seguro, que expira. A senha nunca aparece na resposta.

```
curl -X POST -H "Authorization: Bearer $LUA_TOKEN" \
  "https://painel.lua.email/api/v1/mailboxes/ana@suaempresa.com.br/password"
```

```
{
  "success": true,
  "data": {
    "username": "ana@suaempresa.com.br",
    "link": {"url": "https://pwpush.lua.email/p/abc123def456", "validade_dias": 3, "visualizacoes": 2, "com_frase": false},
    "troca_no_proximo_acesso": true,
    "dominio": "suaempresa.com.br"
  }
}
```

### Desativar ou ativar uma caixa

Envie `"enabled": false` para desativar e `true` para ativar. Uma caixa sem licença não é ativada (409 `caixa_sem_licenca`), e o que está bloqueado por pendência financeira não é reativado (409 `bloqueado_pelo_billing`).

```
curl -X PUT \
  -H "Authorization: Bearer $LUA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Lua-Motivo: Desligamento do colaborador" \
  -d '{"enabled": false}' \
  "https://painel.lua.email/api/v1/mailboxes/ana@suaempresa.com.br/active"
```

### Ajustes de cada caixa

Encaminhamento, apelidos, plano, grupos de serviço, exigências de acesso, mensagens apagadas e aparelhos de celular. Os campos de cada operação estão no painel, em **Suporte > API: documentação e teste**.

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

## 4. Listas de e-mail (aliases)

Uma lista de e-mail é um endereço que entrega a mensagem a vários destinatários. Exige a permissão **Listas e apelidos**.

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

```
curl -X POST \
  -H "Authorization: Bearer $LUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"address_local": "contato", "goto": ["maria@suaempresa.com.br", "ana@suaempresa.com.br"]}' \
  "https://painel.lua.email/api/v1/domains/suaempresa.com.br/aliases"
```

```
response = call("POST", "/domains/suaempresa.com.br/aliases", json={
    "address_local": "contato",
    "goto": ["maria@suaempresa.com.br", "ana@suaempresa.com.br"],
})
print(response.status_code, response.json()["data"]["address"])
```

Cada destinatário de um domínio que está no lua.email precisa existir como caixa ou como lista. Os campos `internal` (a lista só recebe de remetentes internos) e `senders_authhorized` (remetentes autorizados a escrever para a lista) são opcionais.

## 5. Remetentes, IP bloqueado e postmaster

As listas de remetentes permitidos (`branca`) e bloqueados (`negra`) valem para o seu domínio. Exigem a permissão **Listas e apelidos**.

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

```
curl -X POST \
  -H "Authorization: Bearer $LUA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"origem": "fornecedor@exemplo.com.br"}' \
  "https://painel.lua.email/api/v1/domains/suaempresa.com.br/listas/branca"
```

A `origem` é o e-mail ou o domínio de quem envia, e é obrigatória. O `destino`, uma caixa do seu domínio, é opcional; sem ele, a regra vale para todo o domínio. Incluir de novo um remetente que já está na lista responde 409.

A liberação de IP vale só para um IP público que está bloqueado agora e em que uma conta do seu domínio apareceu nos últimos 7 dias. Cada cliente pode ter até 10 liberações ao mesmo tempo, e cada uma vence sozinha depois de 24 horas.

## 6. DNS, domínios alias e roteamento

Exige a permissão **DNS e roteamento**. Alterar registros só é possível com o DNS do domínio ativo na Edgium; caso contrário, a resposta é 409 `dns_fora_da_edgium` e a consulta mostra o que criar no provedor atual.

| Método | Endereço | Permissão | O que faz |
| --- | --- | --- | --- |
| `GET` | `/api/v1/domains/{domain}/dns` | DNS e roteamento | Consulta os registros DNS do domínio. |
| `GET` | `/api/v1/domains/{domain}/dns/expected` | DNS e roteamento | Consulta os registros de e-mail esperados e a conferência no DNS público. |
| `PATCH` | `/api/v1/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` | `/api/v1/domains/{domain}/dns/email/previa` | DNS e roteamento | Mostra a prévia dos registros de e-mail, sem alterar nada. |
| `POST` | `/api/v1/domains/{domain}/dns/email/aplicar` | DNS e roteamento | Aplica os registros de e-mail no DNS. |
| `POST` | `/api/v1/domains/{domain}/dns/email/trocar-mx` | DNS e roteamento | Troca o MX para que os e-mails passem a chegar ao lua.email. |
| `POST` | `/api/v1/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` | `/api/v1/domains/{domain}/alias-domains` | DNS e roteamento | Lista os domínios alias de um domínio. |
| `POST` | `/api/v1/alias-domains` | DNS e roteamento | Cria um domínio alias. |
| `GET` | `/api/v1/alias-domains/{aliasdomain}` | DNS e roteamento | Consulta um domínio alias. |
| `PUT` | `/api/v1/alias-domains/{aliasdomain}` | DNS e roteamento | Altera um domínio alias. |
| `DELETE` | `/api/v1/alias-domains/{aliasdomain}` | DNS e roteamento | Remove um domínio alias. |
| `GET` | `/api/v1/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` | `/api/v1/email-transports/{transport_id}` | DNS e roteamento | Consulta um roteamento por e-mail. |

### Conferir os registros de e-mail e aplicá-los

A consulta devolve, em `data.esperados`, o que o lua.email espera no DNS, junto com o `hash` e a `versao` da prévia. Para aplicar, envie esses dois valores; se a prévia mudou nesse intervalo, a resposta é 409 `plano_mudou` e traz o `hash` novo.

```
check = call("GET", "/domains/suaempresa.com.br/dns/expected").json()["data"]
plan = check["esperados"]
print(check["estado_dns"], plan["resumo"])

response = call("POST", "/domains/suaempresa.com.br/dns/email/aplicar",
                json={"plan_hash": plan["hash"], "versao": plan["versao"]})
print(response.status_code)
```

A troca do MX faz os e-mails passarem a chegar ao lua.email. Ela exige os registros de e-mail já aplicados e `"confirmo": true` no corpo de `/dns/email/trocar-mx`. Sem a confirmação, a resposta é 422 `confirmacao_obrigatoria`.

Na alteração em lote, os registros de e-mail têm proteções: alguns exigem o campo `confirm` e outros só mudam pela ação própria. O DMARC e o SPF não podem ser apagados. Para conferir uma alteração sem gravar, envie `"dry_run": true`.

## 7. Logs de e-mail

Mostra a entrega das mensagens do domínio e a análise do filtro de spam. Exige a permissão **Logs de e-mail** ou **Leitura**.

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

Sem `desde` e `ate`, a consulta cobre as últimas 24 horas. A janela máxima é de 7 dias, dentro dos últimos 180 dias, no horário de Brasília. Os filtros são `remetente`, `destinatario`, `endereco` e `message_id`. A resposta não traz o total: peça a página seguinte enquanto `pagination.tem_proxima` for verdadeiro.

```
curl -H "Authorization: Bearer $LUA_TOKEN" \
  "https://painel.lua.email/api/v1/domains/suaempresa.com.br/logs/mensagens?destinatario=maria@&desde=2026-11-09&ate=2026-11-10"
```

```
params = {"destinatario": "maria@", "desde": "2026-11-09", "ate": "2026-11-10", "per_page": 100}
body = call("GET", "/domains/suaempresa.com.br/logs/mensagens", params=params).json()
for item in body["data"]:
    print(item["quando"], item["remetente"], item["status_texto"], item["caminho"])
```

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

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

A verificação de funcionamento (`/health`) é a única operação que não exige token. As demais, inclusive as do próprio token, exigem o cabeçalho `Authorization: Bearer`.