API do painel: operações e exemplos

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.