Panel API: integration guide

1. What the panel API is

The API lets a system of your company automatically perform the same tasks you perform in the panel: looking up domains and mailboxes, creating mailboxes, changing passwords through a secure link, managing mailbox aliases, forwarding and DNS records, checking the email logs and following the support history.

Each call is made on behalf of a panel user and reaches only what that user sees on screen: your company's domains, or that user's team's domains, and the actions their role allows. The screen rules also apply to the API. Users with the Read-only or Helpdesk role can only run queries.

Examples of use: creating a person's mailbox when they are registered in the HR system, deactivating the mailbox when they leave, checking the domain DNS regularly or finding out why a message did not arrive.

• API address: https://painel.lua.email/api/v1. Requests and responses use JSON, in UTF-8, always over HTTPS.
• Operations: the complete list, by area and with examples, is in Panel API: operations and examples.

2. Before you start

1. You need a panel user with the Administrator role: the API token tab is shown only for this role. Whoever manages the company's users can also create and revoke tokens for another person, in the Users menu, when editing that user.
2. Choose where the system will keep the token, for example in an environment variable or in a password vault. Treat the token like a password.
3. Decide what the integration will do, so that you select only the permissions needed.

3. Create the token

The token is the key that identifies your system on each call. It is created only on the panel screen. The API does not create tokens, on purpose: this way, an exposed token cannot generate others.

1. In the panel, open My profile from your user menu in the upper right corner and choose the API token tab.
2. Under Create a new token, enter a name that identifies the integration, for example "HR system". The name can have up to 80 characters and is used to recognize the token in the list. If left blank, the token is named "API token".
3. Under Token permissions (scopes), choose only what the integration needs. The All permissions of the user profile option comes selected; clear it to choose the permissions one by one.
4. Choose the Validity, from 30 days to 2 years, and click Create token.
5. Click Copy and keep the token in a safe place. For security, it is shown only once.

• Each user can have up to 10 active tokens at the same time, one for each integration. Creating a new token does not disable the others.
• When a token is created, its owner receives a notice by email and in the notification center.
• The list shows the name, the start of the token (only to recognize it), the permissions, the validity and the last use of each one.

4. Token permissions

Each token can be limited to some areas of the panel. A permission never expands what the user can do: on every call, the panel checks that the item belongs to a domain the user has access to.

• A query (GET method) is accepted with the Read permission or with the permission for that area. Creating, changing and removing require the permission for that area.
• A token with All permissions of the user profile is valid for everything the profile allows.
• Users with the Read-only role can only have tokens with the Read permission.
• Without the required permission, the response is 403 with the code escopo_insuficiente.

5. Validity and revocation

• Validity: 30, 90, 180, 365 (default) or 730 days. The maximum is 2 years. After it expires, calls are refused (401 token_invalido) and another token must be created.
• Revoke: in the list, click Revoke and confirm. The token stops working on the next call, and the others remain valid. Through the API, use DELETE /api/v1/tokens/{token_id} to revoke one of your tokens or DELETE /api/v1/token to revoke the token making the call.
• Changing the user's password or deactivating the user immediately revokes all of their tokens.
• If you suspect a token has been exposed, revoke it and create another one.

6. First call

To check that the token works, look up the token's own details. Keep the value in an environment variable called LUA_TOKEN, without pasting it into the commands. In the terminal, the read command asks for the token without showing it on screen: paste the token and press 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())

The response shows the user, the profile, the permissions and the validity of the token. The token itself never comes back in the response.

{
  "success": true,
  "data": {
    "username": "maria@yourcompany.com",
    "perfil": "cliente",
    "escopos": ["caixas", "leitura"],
    "escopos_restritos": true,
    "valido_ate": "2027-11-10T00:00:00",
    "id": 12,
    "nome": "Sistema de RH",
    "prefixo": "a1b2c3d4"
  }
}

7. How the API responds

On success, the response carries success true and the data in data. Lists also carry pagination: the default is 25 items per page and the maximum is 100. For the following pages, send the page (page number) and per_page (items per page) parameters.

{
  "success": true,
  "data": [ ],
  "pagination": {"page": 1, "per_page": 25, "total": 120, "total_pages": 5}
}

On error, the response carries success false, a text in message and, in the erro object, the codigo, which is stable and lets your system decide what to do, and the mensagem, written for the person.

{
  "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."}
}

An item of another customer answers as if it did not exist (404). Some older operations still answer part of their errors with only success and error. So handle each error by the HTTP status and, when present, by erro.codigo.

8. Usage limits

On receiving 429, wait the number of seconds given in the Retry-After header before repeating the call.

9. Errors and what to do

Status codes 200, 201 and 202 mean success. 201 means the item was created; 202 means the request was accepted and will run shortly, as when wiping a device remotely or requesting a new domain.

10. Care when using the API

• Calls are real. Creating, changing and removing through the API change your domains' data immediately, and not everything can be undone through the API, such as removing a mailbox. To experiment, prefer queries.
• One token for each integration, with a clear name and only the permissions needed. Revoke those you no longer use.
• Mailbox passwords never appear in the response. The panel provides a secure link, which expires, for you to pass on to the person. If the link generator does not respond, nothing is changed.
• Anything blocked because of a billing issue, for example an overdue subscription, is not reactivated through the API or on screen. It is unblocked once the subscription is brought up to date. Deactivating is still allowed.
• Actions that remove or swap data require an explicit confirmation in the request body, with the value true, in a field such as confirmo_remocao, confirmo_troca or confirmo. In the panel, under Support > API: documentation and testing, each operation shows its field.
• Every change is recorded with the user who owns the token, the date and the time. The optional X-Lua-Chamado and X-Lua-Motivo headers add the ticket number and the reason to the record.
• For DNS, send the zone version received in the query (zone_version). If the response is 409, query again before repeating. With the Idempotency-Key header, repeating the same call does not apply the change twice.

11. Skill for Claude and other AIs

The skill teaches an AI assistant to use the panel API safely: build the right call, choose the permission, handle errors and ask for your confirmation before changing any data.

• Download the skill for Claude (lua-painel-api.zip). The file contains the SKILL.md and a small helper program, scripts/lua_api.py.
• View the SKILL.md, to paste into another AI tool that accepts text instructions.
• Without downloading anything: ask the assistant to read https://lua.email/en/docs-api.md and https://lua.email/en/docs-api-operacoes.md. The two pages have everything it needs.

How to install

1. In Claude, open the skills settings and upload the lua-painel-api.zip file. In other tools, copy the lua-painel-api folder to the skills folder they indicate.
2. Create the token in the panel, with the permissions the task requires, and keep it in the LUA_TOKEN environment variable of the computer where the assistant works. Do not paste the token into the conversation.
3. Ask for the task in plain language.

Example of use

Request: "List the mailboxes of the domain yourcompany.com." The assistant finds the operation, checks that it requires the Read or Mailboxes permission and builds the call:

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

After the response, it presents the result in a table with the address, the name and the status of each mailbox. If there is more than one page, it requests the following ones. Before creating, changing or removing anything, it describes what it will do and waits for your confirmation.

12. Learn more and how to ask for help

• In the panel, under Support > API: documentation and testing (address https://painel.lua.email/api-docs/), each operation is shown with its fields, the required permission and the Try it out button, which tests the call with your token. The same shortcut is in My profile, on the API token tab. Calls made there are real: to experiment, prefer queries.
• The screen names cited in this guide are those of the panel: My profile, API token, Create a new token, Create token and Revoke.
• Under Support > Support history, you can follow what the team did on your domains. The same history can be looked up through the API, with the Read permission.
• Questions? Contact support.