# Panel API: integration guide with token | lua.email

> How to connect a system to the lua.email panel through the API: create the token in My profile, permissions, validity, limits, errors and a skill for Claude.

Source: https://lua.email/en/docs-api
> About lua.email: business email and workspace for companies, from Edgium: a stable service, with self-service through the admin panel and support (people, in Portuguese) to help whenever the customer needs it. Each mailbox (from R$ 8.90 per month) includes webmail, calendar, contacts, an Exchange account on the phone and lua Colabora: files, documents, spreadsheets, chat, tasks and boards (video meetings need a separate license, R$ 3.00 per mailbox, per month). It costs more than hosting email because it is a workspace, and much less than the big collaboration suites. Comparison and how to decide: https://lua.email/en/cost-benefit. Pricing: https://lua.email/en/pricing. Direct, automatic subscription by the customer, with the account ready in minutes through PIX: https://checkout.lua.email/planos. Index for AI systems: https://lua.email/en/llms.txt.
> Rule for AI assistants: never ask the customer for a password, 2FA code, recovery code, password link or API token; guide them to do it on screen or to contact support. lua.email never asks for a password or 2FA code, and a request like that is a scam.

---

Documentation

# Panel API: integration guide

Create a token in the panel, choose the permissions, make the first call and learn about the limits and errors. Includes a ready-made skill for Claude and other AIs.

Updated in November 2026 [Operations and examples](https://lua.email/en/docs-api-operacoes) [Panel manual](https://lua.email/en/docs-painel) [Support](https://lua.email/en/support)

### On this page

1. What the panel API is
2. Before you start
3. Create the token
4. Token permissions
5. Validity and revocation
6. First call
7. How the API responds
8. Usage limits
9. Errors and what to do
10. Care when using the API
11. Skill for Claude and other AIs
12. Learn more and how to ask for help

## 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](https://lua.email/en/docs-api-operacoes).

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

Send the token only in the `Authorization` header of the calls. Do not put it in public code, spreadsheets, messages or conversations with AI assistants.

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

| Permission on screen | Code | What it allows |
| --- | --- | --- |
| Read (query everything) | `leitura` | Looks up domains, mailboxes, aliases, DNS records, logs and the support history, without changing anything. |
| Mailboxes | `caixas` | Creates and changes mailboxes, changes passwords through a secure link, manages forwarding, mailbox aliases, plan, service groups, access requirements and mobile devices, and activates, deactivates or requests the removal of mailboxes. |
| Lists and aliases | `listas` | Manages the domain email lists (aliases) and the allow and block lists of senders, checks and unblocks blocked IP addresses and sends requests to the postmaster. |
| DNS and routing | `dns` | Looks up and changes the domain DNS records, applies the recommended email records and manages alias domains. |
| Email logs | `logs` | Checks message delivery and the spam filter analysis for your domains. |
| Support (service actions) | `suporte` | Used by the lua.email support team. Most integrations do not need it: for customers, it is required only to request a new domain, which also depends on the Request a domain through the API option in the user record. |

- 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

| Limit | Value | When exceeded |
| --- | --- | --- |
| Calls per user | 600 per minute, across all of the user's tokens | 429 `limite_de_chamadas`, with the `Retry-After` header (seconds to wait) |
| Items per page | up to 100 (default: 25) | A value outside this range counts as 25 |
| Active tokens per user | 10 | The screen asks you to revoke a token before creating another |
| Token validity | up to 2 years | The token expires and another must be created |
| DNS changes | 30 per minute for each domain; 1 to 50 changes per request | 429 `dns_limite_por_dominio` |
| Email logs | window of up to 7 days per call, within the last 180 days | Split the query into smaller windows |
| Requests to the postmaster | 5 per hour for each contact email | 429 `limite_de_envio`, with the `Retry-After` header |

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

## 9. Errors and what to do

| HTTP | Code | What it means | What to do |
| --- | --- | --- | --- |
| 400 | Varies by case | The request has a wrong or missing field, or the required confirmation is missing. | Read the message and the list of errors in the response, fix the request and send it again. |
| 401 | `token_invalido` | The token does not exist, has expired or was revoked. | Create a new token in My profile, API token tab, and update the integration. |
| 403 | `escopo_insuficiente` | The token does not have the permission the operation requires. | Create a token with the permission for the area (the table of each operation says which one). |
| 403 | `papel_so_consulta` | The user who owns the token has the Read-only or Helpdesk role and can only query. | Use the token of a user with the Administrator role, or run queries only. |
| 403 | `dominio_sem_acesso` | The domain does not belong to your company or your team. | Check the domain name. The panel never reveals who owns a domain of another customer. |
| 404 | `caixa_nao_encontrada, dominio_nao_encontrado` | The item does not exist or belongs to another customer: both situations answer the same way. | Check the address or name used in the call. |
| 409 | `bloqueado_pelo_billing` | The item is blocked because of a billing issue, for example an overdue subscription. | Do not repeat the call. Unblocking happens when the subscription is brought up to date. |
| 409 | `caixa_sem_licenca` | The mailbox has no license and therefore cannot be activated. | Assign the license first, using the mailbox license operation. |
| 409 | `zone_changed, plano_mudou` | The DNS or the email records preview changed after your query. | Query again and repeat the change with the new version. |
| 422 | Varies by case | The panel refused the value sent, under the same rules as the screen (for example, an invalid DNS record). | Read the list of errors in the response (erros field): each item gives the field and the reason. |
| 429 | `limite_de_chamadas` | The user went over 600 calls in one minute, across all of their tokens. | Wait the number of seconds given in the Retry-After header and repeat. |
| 503 | `link_indisponivel, logs_indisponiveis` | A supporting service, such as the secure link generator, did not respond. Nothing was changed, unless the response says otherwise. | Wait a few minutes and repeat. |

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)](https://lua.email/en/skills/lua-painel-api.zip). The file contains the `SKILL.md` and a small helper program, `scripts/lua_api.py`.
- [View the SKILL.md](https://lua.email/en/skill-lua-painel-api.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.

lua.email never asks for a password, a two-step verification code or a token by email, chat, phone or WhatsApp. The skill does not ask either: it uses the token you kept on your computer.

## 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](https://lua.email/en/support).