Manual API

Manual API (mail-api)

Manual completo dos endpoints REST atualmente implementados.

Servico

Binario:

bash /root/app/bin/mail-api

Variaveis de ambiente:

• MAIL_API_ADDR (default: :8080)
• MAIL_API_MONGO_URI (default: mongodb://192.168.0.20:27017)
• MAIL_API_MONGO_DB (default: mailcore)
• MAIL_API_TOKEN (opcional)

Autenticacao

Quando MAIL_API_TOKEN estiver definido:

• endpoints protegidos exigem header Authorization: Bearer <token>
• POST /api/v1/auth/login retorna esse token

API keys escopadas (implementado):

• também aceita Authorization: Bearer mk.<token_id>.<secret>;
• escopos suportados: global|tenant|domain|account;
• escopos não-globais aplicam isolamento por recurso;
• requests autenticadas por API key geram auditoria em collection_api_key_audit;
• rate limiting por chave/escopo é aplicado em collection_api_rate_limits.

Observacao:

• POST /api/v1/smtp/submit nao usa Bearer; autentica por email/password no payload.

Convencoes

• Content-Type: application/json
• Erros: { "error": "..." }
• IDs usados na API: tenant_id, domain_id, user_id, mailbox_id, alias_id, api_key_id, whitelist_id, blacklist_id, event_id, fingerprint, hit_id

Endpoints

GET /health

Sem auth. Retorna status e versao do MongoDB.

POST /api/v1/auth/login

Sem payload.

Resposta tipica:

json { "status": "ok", "token": "..." }

Se MAIL_API_TOKEN nao estiver definido, retorna token vazio com note.

GET /api/v1/tenants

Lista tenants.

POST /api/v1/tenants

Payload:

json { "name": "Empresa X" }

GET /api/v1/tenants/:tenant_id

Consulta tenant por ID.

DELETE /api/v1/tenants/:tenant_id

Remove tenant por ID.

GET /api/v1/domains?tenant_id=<tenant_id>

Lista dominios (filtro tenant_id opcional).

POST /api/v1/domains

Payload:

json { "tenant_id": "t_...", "domain": "exemplo.com" }

GET /api/v1/domains/:domain_id

Consulta dominio.

DELETE /api/v1/domains/:domain_id

Remove dominio.

GET /api/v1/users?tenant_id=<tenant_id>

Lista usuarios (filtro tenant_id opcional).

POST /api/v1/users

Payload:

json { "tenant_id": "t_...", "domain_id": "d_...", "email": "user@exemplo.com", "name": "Usuario", "password": "Senha#123" }

Observacao:

• password e opcional; se presente, exige 8+ caracteres para ser aplicada.

GET /api/v1/users/:user_id

Consulta usuario.

DELETE /api/v1/users/:user_id

Remove usuario.

POST /api/v1/users/:user_id/password

Payload:

json { "password": "NovaSenha#123" }

Regra: minimo 8 caracteres.

POST /api/v1/smtp/submit

Nao exige Bearer.

Payload:

json { "email": "user@exemplo.com", "password": "Senha#123", "from": "user@exemplo.com", "to": "destino@outrodominio.com", "subject": "Assunto", "text": "Corpo" }

Regras:

• from e opcional; se ausente usa email
• exige email, password, to, subject, text
• aplica enforcement de quota smtp_sent por hierarquia (tenant > domain > mailbox) quando configurado.

Resposta:

json { "status": "queued", "queue_id": "q_..." }

GET /api/v1/queues/outbound?status=queued

Lista fila outbound (filtro status opcional).

POST /api/v1/mailboxes/:mailbox_id/spamtrap/enable

Payload:

json { "mode": "hard", "notes": "texto" }

mode aceito: hard|soft|silent (default hard).

POST /api/v1/mailboxes/:mailbox_id/spamtrap/disable

Sem payload.

GET /api/v1/mailboxes/:mailbox_id/spamtrap

Consulta estado spamtrap da mailbox.

GET /api/v1/aliases?domain=<dominio>&target=<email>&all=1

Lista aliases.

Filtros opcionais:

• domain=<dominio>
• target=<email> (campo target_address)
• all=1 (inclui aliases fora de status=active)

POST /api/v1/aliases

Payload:

json { "address": "vendas@exemplo.com", "target_address": "usuario@exemplo.com" }

Cria ou atualiza alias (upsert) com vínculo para mailbox alvo ativa.

GET /api/v1/aliases/:alias_id

Consulta alias por ID.

DELETE /api/v1/aliases/:alias_id

Remove alias por ID.

POST /api/v1/aliases/:alias_id/spamtrap/enable

Payload:

json { "mode": "hard" }

mode aceito: hard|soft|silent (default hard).

POST /api/v1/aliases/:alias_id/spamtrap/disable

Sem payload.

GET /api/v1/aliases/:alias_id/spamtrap

Consulta estado spamtrap do alias.

GET /api/v1/apikeys

Lista API keys (somente escopo global).

Filtros opcionais:

• scope_type=global|tenant|domain|account
• scope_id=<id>
• status=active|revoked

POST /api/v1/apikeys

Cria API key (somente escopo global).

Payload:

json { "name": "tenant-key", "scope_type": "tenant", "scope_id": "t_...", "ttl_days": 90, "rate_limit_per_minute": 300, "permissions": ["users.read", "users.write"] }

Observações:

• retorno inclui token apenas na resposta de criação;
• formato do token: mk.<token_id>.<secret>;
• para escopos não-globais, scope_id é obrigatório;
• ttl_days default:
• global: sem expiração por padrão;
• demais escopos: 90 dias.

DELETE /api/v1/apikeys/:api_key_id

Revoga API key (status revoked).

POST /api/v1/apikeys/:api_key_id/revoke

Revoga API key (alternativa semântica ao DELETE).

GET /api/v1/quotas

Lista regras de quota (somente escopo global).

Filtros opcionais:

• scope_type=tenant|domain|mailbox
• scope_id=<id>
• metric=api_calls|smtp_sent|storage_bytes

POST /api/v1/quotas

Cria/atualiza quota (upsert, somente escopo global).

Payload:

json { "scope_type": "tenant", "scope_id": "t_...", "metric": "api_calls", "soft_limit": 100000, "hard_limit": 120000, "period": "monthly" }

Regras de enforcement em runtime:

• soft_limit: gera evento de alerta (quota.soft_exceeded) sem bloquear;
• hard_limit:
• escopos domain|mailbox: bloqueio controlado;
• escopo tenant: segue política da conta de billing:
  • overage_mode=invoice: permite exceder e cobra no fechamento;
  • overage_mode=block: bloqueia no hard-limit;
  • auto_upgrade=true: tenta upgrade automático de plano antes de bloquear.

GET /api/v1/usage

Lista contadores de uso (somente escopo global).

Filtros opcionais:

• month=YYYY-MM (default mês atual)
• scope_type=tenant|domain|mailbox
• scope_id=<id>
• metric=api_calls|smtp_sent|storage_bytes

Observação:

• api_calls é incrementado para requests autenticadas por API key escopada;
• smtp_sent é incrementado por submissão aceita em /api/v1/smtp/submit.

GET /api/v1/billing/accounts

Lista contas de billing (somente escopo global).

Filtros opcionais:

• tenant_id=<tenant_id>
• status=active|past_due|suspended|canceled

POST /api/v1/billing/accounts

Cria/atualiza conta de billing por tenant (upsert, escopo global).

Payload:

json { "tenant_id": "t_...", "plan_code": "start", "currency": "BRL", "status": "active", "day_anchor": 15, "overage_mode": "invoice", "auto_upgrade": true, "auto_upgrade_max_plan_code": "scale" }

Campos adicionais:

• overage_mode: invoice|block (default invoice);
• auto_upgrade: true|false (default false);
• auto_upgrade_max_plan_code: start|growth|scale (default scale).

GET /api/v1/billing/accounts/:billing_account_id

Consulta conta de billing por ID.

GET /api/v1/billing/prices

Lista tabela de preços.

POST /api/v1/billing/prices

Cria/atualiza preço (upsert).

Payload:

json { "code": "overage.smtp_sent.1000", "currency": "BRL", "unit_cents": 140, "unit": "block_1000", "active": true }

GET /api/v1/billing/invoices

Lista invoices.

Filtros opcionais:

• month=YYYY-MM
• billing_account_id=<id>
• status=draft|open|paid|void|uncollectible

GET /api/v1/billing/invoices/:invoice_id

Consulta invoice com itens.

POST /api/v1/billing/close

Fecha invoices do mês para contas ativas (ou para uma conta específica).

Payload:

json { "month": "2026-03", "billing_account_id": "ba_..." }

Observação:

• quando billing_account_id não é enviado, processa todas as contas ativas.

GET /api/v1/whitelists

Filtros opcionais:

• scope=mailbox|domain|global
• scope_ref=<id>
• mailbox_id=<mailbox_id>

POST /api/v1/whitelists

Payload:

json { "scope": "mailbox", "scope_ref": "m_...", "mailbox_id": "m_...", "type": "sender", "value": "noreply@exemplo.com", "spamtrap_bypass_allowed": false }

Regras:

• scope: mailbox|domain|global (default mailbox)
• type: sender|domain
• para scope=global, scope_ref vira global
• para scope=mailbox, scope_ref pode vir de mailbox_id

DELETE /api/v1/whitelists/:whitelist_id

Remove whitelist por ID.

GET /api/v1/blacklists?type=<tipo>&active=1

Lista blacklists.

Filtros opcionais:

• type=ip|cidr|sender|domain|fingerprint|helo
• active=1 (default; apenas regras ativas)
• active=0 (inclui expiradas/inativas)

POST /api/v1/blacklists

Payload:

json { "type": "cidr", "value": "203.0.113.0/24", "action": "tempfail", "reason": "burst abuse source network", "ttl_seconds": 86400 }

Campos:

• type obrigatório: ip|cidr|sender|domain|fingerprint|helo
• value obrigatório (normalizado/validado por tipo)
• action opcional: reject|tempfail (default reject)
• reason opcional
• ttl_seconds opcional (>0) para expiração automática
• expires_at opcional (timestamp UTC); alternativa a ttl_seconds

DELETE /api/v1/blacklists/:blacklist_id

Remove blacklist por ID.

GET /api/v1/policy/watchlist

Lista watchlist.

GET /api/v1/policy/watchlist/:fingerprint

Consulta fingerprint.

DELETE /api/v1/policy/watchlist/:fingerprint

Remove fingerprint.

GET /api/v1/policy/reputation/ip/:ip

Consulta reputacao por IP.

GET /api/v1/policy/reputation/domain/:domain

Consulta reputacao por dominio.

GET /api/v1/policy/reputation/sender/:sender

Consulta reputacao por sender.

GET /api/v1/policy/reputation/fingerprint/:fingerprint

Consulta reputacao por fingerprint.

Observacao:

• quando nao encontrado, retorna HTTP 200 com status: not_found.

GET /api/v1/policy/graylist

Lista eventos de graylist.

POST /api/v1/policy/graylist/:event_id/release

Libera e reprocessa mensagens held associadas ao event_id.

DELETE /api/v1/policy/graylist/:fingerprint

Remove eventos de graylist por fingerprint.

GET /api/v1/policy/spamtrap/hits?domain=<dominio>

Lista hits de spamtrap (filtro domain opcional).

GET /api/v1/policy/spamtrap/hits/:hit_id

Consulta hit especifico por ID.

Precedencia de policy (inbound RCPT)

• whitelist aplicada primeiro
• blacklist aplicada em seguida (quando nao houver whitelist)
• depois entram watchlist, reputacao, spamtrap e burst/graylist

Codigos HTTP comuns

• 200: sucesso
• 201: criado
• 202: aceito/enfileirado
• 400: erro de validacao/payload
• 401: nao autorizado
• 404: nao encontrado
• 405: metodo nao permitido
• 500: erro interno

Manual CLI

Manual CLI (mailctl)

Manual completo dos comandos atualmente implementados no mailctl.

Binario

bash /root/app/bin/mailctl

Configuracao

Variaveis de ambiente:

• MAILCTL_MONGO_URI (default: mongodb://192.168.0.20:27017)
• MAILCTL_MONGO_DB (default: mailcore)
• MAILCTL_JSON=1 habilita saida JSON por padrao
• MAILCTL_CERT_CONFIG (default: /root/app/cert-tools.json)
• MAILCTL_NO_CERT_PROMPT=1 desativa prompt de cert no domain create
• MAILCTL_NO_DKIM_AUTO=1 desativa geracao automatica de DKIM no domain create
• MAIL_SMTP_OUT_HELO define o host de borda usado nas sugestoes DNS (A/AAAA/MX/SPF) para modo multi-dominio

Formato de saida

• Humano: padrao
• JSON: usar --json (ou MAILCTL_JSON=1)

Comandos

health

bash mailctl [--json] health

Retorna status e versao do MongoDB.

tenant

Criar tenant:

bash mailctl [--json] tenant create --name <nome>

Listar tenants:

bash mailctl [--json] tenant list

Detalhar tenant:

bash mailctl [--json] tenant info <tenant_id>

domain

Criar dominio:

bash mailctl [--json] domain create <domain> --tenant <tenant_id> [--no-cert-prompt] [--no-dkim-auto]

Listar dominios:

bash mailctl [--json] domain list [--tenant <tenant_id>]

Remover dominio:

bash mailctl [--json] domain delete <domain|domain_id> [--force]

Regras:

• sem --force, o comando bloqueia se houver dependencias (users/mailboxes/aliases);
• com --force, remove dominio e dados relacionados do dominio (contas, credenciais, mailboxes/pastas, aliases e artefatos de quota/usage/api key por escopo de dominio/conta).

Gerar DKIM:

bash mailctl [--json] domain dkim gen <domain|domain_id> [--selector mail] [--force]

Regra de seguranca:

• sem --force, se já existir DKIM no domínio, a chave atual é mantida (não gira);
• use --force somente quando quiser rotacionar a chave DKIM.

Consultar DKIM sem regenerar chave:

bash mailctl [--json] domain dkim show <domain|domain_id>

Consultar sugestao completa de DNS sem regenerar chave:

bash mailctl [--json] domain dns show <domain|domain_id>

Observacao:

• Alem do registro DKIM, o comando agora retorna sugestoes completas para zona DNS:
• A
• AAAA (opcional)
• MX
• SPF (TXT)
• DKIM (TXT)
• DMARC (TXT)
• Em ambiente multi-dominio com IP/PTR unicos, o host sugerido para A/AAAA/MX/SPF vem de MAIL_SMTP_OUT_HELO (ex.: mail.gratis.com.br).
• O A/AAAA e preenchido por resolucao DNS do host definido em MAIL_SMTP_OUT_HELO; se nao resolver, mantem placeholder.
• Se o host MX/HELO for externo a zona do dominio (ex.: dominio lalala.com.br usando mail.gratis.com.br), a sugestao da zona do dominio nao inclui A/AAAA do host externo; nesse caso, o A/AAAA deve ser gerenciado na zona do proprio host MX.

Observacao sobre prompt de certificado no domain create:

• so aparece em terminal interativo;
• nao aparece com --json, --no-cert-prompt ou MAILCTL_NO_CERT_PROMPT=1;
• depende de prompt_on_domain_create=true no cert-tools.json.

Observacao sobre DKIM automatico no domain create:

• por padrao, ao criar dominio o mailctl gera DKIM automaticamente;
• no retorno, imprime (ou retorna em JSON) a tabela DNS completa (A, AAAA, MX, SPF, DKIM, DMARC);
• para desativar nesse comando: --no-dkim-auto;
• para desativar por ambiente: MAILCTL_NO_DKIM_AUTO=1.

cert

Gerar certificado para dominio (por dominio ou domain_id):

bash mailctl [--json] cert generate <domain|domain_id> [--provider <nome>] [--email <email>]

Consultar metadados TLS do dominio:

bash mailctl [--json] cert show <domain|domain_id>

user

Criar usuario (com senha opcional):

bash mailctl [--json] user create <email> --name <nome> --tenant <tenant_id> --domain <domain|domain_id> [--password <senha>]

Regra:

• --domain aceita domínio textual (ex.: lalala.com.br) ou domain_id;
• o domínio informado deve pertencer ao tenant_id informado.
• se --password não for enviado, o mailctl gera senha automaticamente (8 caracteres, letras+números) e a devolve na resposta de criação.

Definir/atualizar senha:

bash mailctl [--json] user passwd <email> --password <senha>

Listar usuarios:

bash mailctl [--json] user list [--tenant <tenant_id>]

smtp

Submeter email outbound:

bash mailctl [--json] smtp submit --from <email> --to <email> --subject <txt> --text <txt>

Listar fila outbound:

bash mailctl [--json] smtp queue list [--status queued|retry|processing|delivered|failed]

Forcar retry de item da fila:

bash mailctl [--json] smtp queue retry <queue_id>

mailbox spamtrap

Habilitar spamtrap de mailbox:

bash mailctl [--json] mailbox spamtrap enable <email> [--mode hard|soft|silent] [--notes <texto>]

Desabilitar spamtrap de mailbox:

bash mailctl [--json] mailbox spamtrap disable <email>

Consultar spamtrap de mailbox:

bash mailctl [--json] mailbox spamtrap info <email>

Listar mailboxes spamtrap:

bash mailctl [--json] mailbox spamtrap list [--domain <dominio>]

alias

Criar alias:

bash mailctl [--json] alias create <alias_email> <target_email>

Listar aliases:

bash mailctl [--json] alias list [--domain <dominio>] [--target <email>] [--all]

alias spamtrap

Habilitar spamtrap de alias:

bash mailctl [--json] alias spamtrap enable <email> [--mode hard|soft|silent]

Desabilitar spamtrap de alias:

bash mailctl [--json] alias spamtrap disable <email>

Listar aliases spamtrap:

bash mailctl [--json] alias spamtrap list [--domain <dominio>]

whitelist

Escopos:

• mailbox (padrao)
• domain
• global

Adicionar whitelist:

bash mailctl [--json] whitelist add [--scope mailbox|domain|global] [--mailbox <email>|--domain-id <domain_id>] (--sender <sender>|--domain <dominio>) [--spamtrap-bypass]

Remover whitelist:

bash mailctl [--json] whitelist remove [--scope mailbox|domain|global] [--mailbox <email>|--domain-id <domain_id>] (--sender <sender>|--domain <dominio>)

Listar whitelist:

bash mailctl [--json] whitelist list [--scope mailbox|domain|global] [--mailbox <email>|--domain-id <domain_id>]

Regras de escopo:

• scope=mailbox: exige --mailbox <email>
• scope=domain: exige --domain-id <domain_id>
• scope=global: nao exige identificador adicional

blacklist

Tipos suportados:

• ip
• cidr (IPv4/IPv6, ex.: 203.0.113.0/24)
• sender
• domain
• fingerprint
• helo

Adicionar blacklist:

bash mailctl [--json] blacklist add --type ip|cidr|sender|domain|fingerprint|helo --value <valor> [--action reject|tempfail] [--ttl <duracao>] [--reason <texto>]

Remover blacklist:

bash mailctl [--json] blacklist remove (--id <blacklist_id> | --type ip|cidr|sender|domain|fingerprint|helo --value <valor>)

Listar blacklist:

bash mailctl [--json] blacklist list [--type ip|cidr|sender|domain|fingerprint|helo] [--all]

Observacoes:

• Sem --all, lista apenas regras ativas (nao expiradas).
• --action reject retorna bloqueio permanente (554 no SMTP inbound).
• --action tempfail retorna bloqueio temporario (451 no SMTP inbound).
• Precedencia no inbound: whitelist > blacklist > watchlist/reputacao/graylist.

apikey

Criar API key:

bash mailctl [--json] apikey create [--name <nome>] [--scope-type global|tenant|domain|account] [--scope-id <id>] [--ttl-days <dias>] [--rpm <n>] [--perm <perm>]

Observacoes:

• formato do token retornado: mk.<token_id>.<secret>;
• o token completo so aparece na resposta de criacao;
• para escopos nao-globais, --scope-id e obrigatorio;
• sem --rpm, aplica default por escopo.

Listar API keys:

bash mailctl [--json] apikey list [--scope-type global|tenant|domain|account] [--scope-id <id>] [--status active|revoked]

Revogar API key:

bash mailctl [--json] apikey revoke <api_key_id>

quota

Criar/atualizar quota:

bash mailctl [--json] quota set --scope-type tenant|domain|mailbox --scope-id <id> --metric api_calls|smtp_sent|storage_bytes --soft <n> --hard <n> [--period monthly]

Listar quotas:

bash mailctl [--json] quota list [--scope-type tenant|domain|mailbox] [--scope-id <id>] [--metric api_calls|smtp_sent|storage_bytes]

usage

Consultar uso consolidado:

bash mailctl [--json] usage show [--month YYYY-MM] [--scope-type tenant|domain|mailbox] [--scope-id <id>] [--metric api_calls|smtp_sent|storage_bytes]

billing

Conta de billing (upsert):

bash mailctl [--json] billing account set --tenant <tenant_id> --plan start|growth|scale [--status active] [--currency BRL] [--day-anchor 1..28] [--overage-mode invoice|block] [--auto-upgrade true|false] [--auto-upgrade-max-plan start|growth|scale]

Observacoes:

• --overage-mode invoice (default): permite excedente no tenant e cobra overage em fatura;
• --overage-mode block: bloqueia no hard-limit do tenant;
• --auto-upgrade true: tenta subir de plano automaticamente ao atingir hard-limit (ate --auto-upgrade-max-plan).

Listar contas de billing:

bash mailctl [--json] billing account list [--tenant <tenant_id>] [--status active|past_due|suspended|canceled]

Preco (upsert):

bash mailctl [--json] billing price set --code <code> --unit-cents <n> [--unit <u>] [--currency BRL] [--active true|false]

Listar precos:

bash mailctl [--json] billing price list [--code <code>]

Listar invoices:

bash mailctl [--json] billing invoice list [--month YYYY-MM] [--billing-account <id>] [--status draft|open|paid|void|uncollectible]

Detalhar invoice:

bash mailctl [--json] billing invoice show <invoice_id>

Fechamento mensal:

bash mailctl [--json] billing close [--month YYYY-MM] [--billing-account <id>]

policy watchlist

bash mailctl [--json] policy watchlist list mailctl [--json] policy watchlist info <fingerprint> mailctl [--json] policy watchlist remove <fingerprint>

policy reputation

bash mailctl [--json] policy reputation show --fingerprint <fp> mailctl [--json] policy reputation show --ip <ip> mailctl [--json] policy reputation show --sender <sender> mailctl [--json] policy reputation show --domain <domain>

policy graylist

bash mailctl [--json] policy graylist list mailctl [--json] policy graylist release <event_id> mailctl [--json] policy graylist remove <fingerprint>

policy burst

bash mailctl [--json] policy burst show --fingerprint <fingerprint> mailctl [--json] policy burst list [--active]

spamtrap hits

bash mailctl [--json] spamtrap hits list [--domain <dominio>] mailctl [--json] spamtrap hits show <hit_id>

Exemplo rapido

bash mailctl --json tenant list mailctl --json domain list --tenant t_123 mailctl --json policy graylist release gl_123

Billing

Billing (BRL) e Desenho Tecnico de Cobranca

Documento de referencia para modelo comercial, quotas, rate limiting e metering.

Objetivo

Definir um modelo vendavel para mercado (SaaS/B2B + developers) com:

• precificacao em BRL;
• cobranca por assinatura + consumo;
• controles tecnicos de quotas e rate limiting por escopo;
• trilha de auditoria e fechamentos de fatura.

Modelo Comercial

Escopos de produto:

• tenant: conta pagante principal.
• domain: unidade delegavel dentro do tenant (pode ter owner delegado).
• account: usuario/caixa para uso operacional e API.

Direcao de venda:

• plano base por tenant;
• delegacao por dominio (multi-marca/agencia/franquia);
• addon de API por uso para integracoes de devs e automacoes.

Pacote comercial vendavel (forma de contrato)

Para cada tenant, vender como pacote base com limites contratados:

• X domínios ativos;
• X contas (mailboxes) ativas;
• X bytes de storage total;
• opcionalmente X envios/mês e X chamadas API/mês.

Modelo de excedente:

• acima do contratado, cobrar overage por unidade (dominio, conta, GB, 1k envios, 100k API calls).
• opcao de auto-upgrade de plano quando ultrapassar thresholds recorrentes.

Tabela Inicial (BRL)

| Plano | Preco/mês | Caixas incluidas | Dominios incluidos | Envio incluido/mês | API incluida/mês | Storage incluido | Excedente envio | Excedente API | Excedente storage | |---|---:|---:|---:|---:|---:|---:|---:|---:|---:| | Start | R$ 149 | 20 | 3 | 50.000 | 200.000 req | 100 GB | R$ 1,80 / 1.000 | R$ 1,20 / 100.000 | R$ 0,35 / GB | | Growth | R$ 499 | 100 | 15 | 300.000 | 2.000.000 req | 500 GB | R$ 1,40 / 1.000 | R$ 0,90 / 100.000 | R$ 0,30 / GB | | Scale | R$ 1.490 | 500 | 80 | 1.500.000 | 12.000.000 req | 2 TB | R$ 1,10 / 1.000 | R$ 0,70 / 100.000 | R$ 0,25 / GB | | Enterprise | sob consulta | custom | custom | custom | custom | custom | custom | custom | custom |

Add-ons sugeridos:

• dominio extra: R$ 12/mês;
• caixa extra: R$ 4,90/mês;
• IP dedicado de envio: R$ 390/mês;
• retencao estendida de auditoria (12 meses): R$ 99/mês por tenant.

Quotas (Tecnico)

Hierarquia obrigatoria:

• tenant > domain > mailbox.

Regras:

• limite efetivo do nivel inferior nao pode exceder limite disponivel do nivel superior;
• suporte a soft_limit (alerta) e hard_limit (bloqueio controlado);
• avaliacao de quota em escrita/ingestao e operacoes de envio/API.
• toda alocacao de subcota deve reduzir saldo disponivel do escopo pai.

Delegacao operacional de quotas:

• tenant owner:
• distribui quotas para domínios e contas dentro do próprio tenant;
• pode revender internamente desde que respeite limites do tenant.
• domain owner (delegado pelo tenant):
• distribui quotas apenas para contas do próprio domínio;
• nao pode criar capacidade acima da quota do domínio.
• account:
• consome quota alocada; nao redistribui quota.

Regras de consistencia:

• soma de quotas de dominios <= quota do tenant;
• soma de quotas de contas de um dominio <= quota do dominio;
• limites de contagem (domains, accounts) e volume (storage, smtp_sent, api_calls) obedecem a mesma hierarquia.

Metricas base para quota:

• smtp_sent (contador de envio);
• api_calls (contador de chamadas autenticadas);
• storage_bytes (uso de armazenamento).

Rate Limiting

Escopos de rate limit:

• api_key_id;
• tenant_id;
• domain_id;
• account_id;
• ip.

Modelo recomendado:

• janelas 1m e 1h com burst;
• decisao por menor limite disponivel entre escopos aplicaveis;
• respostas de excesso:
• API: 429 Too Many Requests;
• SMTP inbound/submission: 451 temporario quando aplicavel.

Metering e Cobranca

Colecoes sugeridas

• collection_billing_accounts
• collection_billing_prices
• collection_quota_limits
• collection_usage_counters
• collection_invoices
• collection_invoice_items
• collection_billing_events

Campos minimos

collection_billing_accounts:

• billing_account_id
• tenant_id
• plan_code
• status (active|past_due|suspended|canceled)
• billing_cycle_anchor
• currency (BRL)
• created_at, updated_at

collection_usage_counters (granularidade diaria):

• usage_id
• day (YYYY-MM-DD)
• tenant_id
• domain_id (opcional)
• account_id (opcional)
• metric (smtp_sent|api_calls|storage_bytes_avg)
• value
• source (smtp_out|api|store)
• idempotency_key
• created_at, updated_at

collection_quota_limits:

• quota_id
• scope_type (tenant|domain|mailbox)
• scope_id
• parent_scope_type (opcional)
• parent_scope_id (opcional)
• metric
• soft_limit
• hard_limit
• allocated
• remaining
• period (monthly)
• created_at, updated_at

collection_invoices:

• invoice_id
• billing_account_id
• period_start, period_end
• subtotal, discount_total, tax_total, total
• currency (BRL)
• status (draft|open|paid|void|uncollectible)
• issued_at, due_at

collection_invoice_items:

• item_id
• invoice_id
• type (base|overage|addon|discount|tax)
• description
• quantity
• unit_price
• amount
• metric (quando aplicavel)

Pipeline operacional

1. Servicos emitem eventos de uso (smtp_sent, api_calls, storage_bytes).
2. Worker de metering agrega em collection_usage_counters com idempotencia.
3. Job diario recalcula media de storage e verifica soft/hard limit.
4. Job de fechamento mensal gera fatura (collection_invoices + items).
5. Aplicacao de politicas por status de cobranca:
6. past_due: alertas e reducao de limite opcional;
7. suspended: bloqueio de escrita/envio/API conforme regra.

Formula de total:

total = mensalidade_base + excedentes + add-ons - descontos + impostos

API Keys e Billing

Diretriz de autenticacao comercial:

• chave master global da plataforma continua existindo;
• chaves escopadas por tenant|domain|account habilitam produto vendavel por consumo;
• cada request autenticada por chave deve gerar evento de uso e auditoria.

Politica de escopo (v1):

• global: acesso administrativo completo da plataforma.
• tenant: acesso apenas a recursos do proprio tenant.
• domain: acesso apenas a recursos do proprio dominio.
• account: acesso apenas a propria conta de e-mail e gerenciamento de aliases vinculados a mailbox da conta.

Campos de auditoria por request:

• api_key_id
• scope_type, scope_id
• tenant_id, domain_id, account_id
• route, method, status_code, latency_ms
• source_ip
• created_at

Politicas recomendadas de bloqueio

Ao exceder hard limit:

• api_calls: responder 429;
• smtp_sent: rejeitar envio com erro temporario/controlado;
• storage_bytes: bloquear novas gravacoes (mantendo leitura e administracao).

Ao exceder soft limit:

• manter servico;
• gerar alerta operacional/comercial;
• destacar no dashboard/relatorio.

Roadmap tecnico (ordem sugerida)

1. API keys escopadas com permissoes finas e auditoria.
2. Rate limiting por escopo com armazenamento de contadores.
3. Quotas multinivel (tenant > domain > mailbox) com enforcement.
4. Metering consolidado e fechamento de fatura.
5. Integracao de pagamento e ciclo comercial completo.