Panel API: operations and examples

1. Before the examples

All examples use the token kept in the LUA_TOKEN environment variable and the address https://painel.lua.email/api/v1. To create the token and learn about permissions, limits and errors, read the integration guide.

In the Python examples, the call function below sends the call and, if the panel asks for a pause (429), waits the time indicated and tries again. The other Python examples use this function.

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")))

In the addresses, what is between braces, such as {domain} or {mailbox}, must be replaced with the domain or the full mailbox address. The examples use the fictional domain yourcompany.com.

In the tables, the Permission column shows the permission for the area. Every query (GET) is also accepted with the Read permission; creating, changing and removing require the permission for the area.

2. Domains

Looks up your company's or your team's domains, with the Read permission. Requesting a new domain requires the Support permission and the Request a domain through the API option enabled in the user record.

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

Operations to list, create, activate, deactivate and remove mailboxes, change the password and check storage use.

List the mailboxes of a domain

Only active mailboxes by default. Use active_only=false to include inactive ones and search to look for part of the address or name.

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

body = call("GET", "/domains/yourcompany.com/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@yourcompany.com",
      "name": "Maria Souza",
      "domain": "yourcompany.com",
      "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}
}

Create a mailbox

Requires the Mailboxes permission. The password must meet the panel password policy. The license (x_client_license_id) defines the mailbox plan and storage; it must belong to your company and have a free seat. The license number appears in the x_client_license_id field of existing mailboxes. A mailbox without a license cannot be activated.

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

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

Change a mailbox password

The panel generates a new password, changes the mailbox password and returns only the address of a secure link, which expires. The password never appears in the response.

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

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

Deactivate or activate a mailbox

Send "enabled": false to deactivate and true to activate. A mailbox without a license is not activated (409 caixa_sem_licenca), and anything blocked because of a billing issue is not reactivated (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@yourcompany.com/active"

Mailbox settings

Forwarding, mailbox aliases, plan, service groups, access requirements, deleted messages and mobile devices. The fields of each operation are in the panel, under Support > API: documentation and testing.

4. Email lists (aliases)

An email list is an address that delivers the message to several recipients. Requires the Lists and aliases permission.

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

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

Each recipient in a domain hosted at lua.email must exist as a mailbox or as a list. The internal (the list receives only from internal senders) and senders_authhorized (senders allowed to write to the list) fields are optional.

5. Senders, blocked IP and postmaster

The lists of allowed (branca) and blocked (negra) senders apply to your domain. They require the Lists and aliases permission.

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/yourcompany.com/listas/branca"

The origem is the email address or domain of the sender, and is required. The destino, a mailbox in your domain, is optional; without it, the rule applies to the whole domain. Adding a sender that is already on the list again returns 409.

Unblocking applies only to a public IP address that is blocked right now and where an account in your domain appeared in the last 7 days. Each customer can have up to 10 unblocks at the same time, and each one expires on its own after 24 hours.

6. DNS, alias domains and routing

Requires the DNS and routing permission. Records can be changed only while the domain DNS is active at Edgium; otherwise the response is 409 dns_fora_da_edgium and the query shows what to create at the current provider.

Check the email records and apply them

The query returns, in data.esperados, what lua.email expects in DNS, together with the hash and the versao of the preview. To apply, send these two values; if the preview changed in the meantime, the response is 409 plano_mudou and carries the new hash.

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

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

Changing the MX makes emails start arriving at lua.email. It requires the email records to be applied first and "confirmo": true in the body of /dns/email/trocar-mx. Without the confirmation, the response is 422 confirmacao_obrigatoria.

7. Email logs

Shows message delivery for the domain and the spam filter analysis. Requires the Email logs or Read permission.

Without desde and ate, the query covers the last 24 hours. The maximum window is 7 days, within the last 180 days, in Brasília time. The filters are remetente, destinatario, endereco and message_id. The response does not include the total: request the next page while pagination.tem_proxima is true.

curl -H "Authorization: Bearer $LUA_TOKEN" \
  "https://painel.lua.email/api/v1/domains/yourcompany.com/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/yourcompany.com/logs/mensagens", params=params).json()
for item in body["data"]:
    print(item["quando"], item["remetente"], item["status_texto"], item["caminho"])

8. Check, token and support history

The operating check (/health) is the only operation that does not require a token. All the others, including those of the token itself, require the Authorization: Bearer header.