Visão geral da API REST da TrekMail para desenvolvedores

A API da TrekMail permite gerenciar domínios, caixas de correio, encaminhamento, DNS, migrações de e-mail e operações de webmail usando um cliente HTTP ou agente de IA. Isso inclui ler e enviar mensagens, rascunhos, agendamento, pastas, contatos, calendários, identidades, modelos e remetentes bloqueados. As solicitações autenticadas usam um token bearer, as respostas são JSON e a atividade da API é registrada para auditoria.

O que você recebe

• API REST v1 com formato JSON de solicitação e resposta.
• Autenticação com token bearer: sem cookies ou sessões em chamadas autenticadas da API.
• Chaves de idempotência nas operações de gravação que as exigem, evitando trabalho duplicado durante novas tentativas.
• Limite de taxa por token com cabeçalhos Retry-After.
• Log de auditoria visível no dashboard em AI Agents & API → Audit Log.
• Servidor MCP com catálogo filtrado pelas credenciais, transporte e configurações de segurança da conexão atual. Portanto, uma conexão restrita a um projeto vê somente as ferramentas que pode usar.
• Aliases de domínio: conecte endereços somente para recebimento de um domínio secundário às mesmas partes locais de um domínio principal, com estados de entrega salvos e ativos, além de remoção segura. Consulte Aliases de domínio via API e MCP.
• Arquitetura de dois tokens: tokens de operações separados para infraestrutura e tokens de mensagens para operações completas de e-mail, como leitura, envio, rascunhos, agendamento, contatos, calendários, identidades, modelos e pastas.
• Informações sobre entregabilidade de saída e devoluções: obtenha no dashboard o resumo de enviados, entregues, devoluções permanentes e temporárias, além de códigos e respostas SMTP por destinatário. Consulte Entregabilidade e devoluções.
• Uso do armazenamento da caixa de correio: list_mailboxes e get_mailbox retornam used_mb, quota_mb, allocation_mb e is_pooled, para que um agente identifique caixas próximas do limite sem acessar o dashboard.
• Administração White Label: verifique a configuração, gerencie o branding por domínio, convide clientes, controle funções e domínios, suspenda ou restaure o acesso e analise a atividade pela API ou MCP. Consulte o guia de branding e o guia de gerenciamento de equipes.

API do Drive e automação de arquivos

O Drive faz parte da API pública. Ele abrange espaços do Drive da conta e das caixas de correio, uso, navegação em pastas, uploads, gerenciamento de arquivos e pastas, Lixeira, ações em massa, links públicos de compartilhamento, gerenciamento de senhas de dispositivos de sincronização e o status somente leitura do complemento Drive Storage.

O Drive usa onze escopos de tokens de operações: drive:account:read, drive:account:write, drive:account:share, drive:account:purge, drive:mailbox:read, drive:mailbox:write, drive:mailbox:share, drive:mailbox:purge, drive:addon:read, drive:devices:read e drive:devices:write. As ações de cobrança do complemento Drive, como compra, redimensionamento e cancelamento, continuam disponíveis apenas no dashboard e não são expostas como operações de gravação por API ou MCP.

Comece pela Visão geral da API do Drive ou pelo Início rápido da API do Drive.

Arquitetura de dois tokens

A API usa dois tipos independentes de token. Você pode usar um ou ambos conforme suas necessidades:

Tokens de operações e tokens de mensagens têm escopos e limites de taxa separados. Um único agente pode usar os dois tokens simultaneamente ao configurá-los no ambiente do servidor MCP.

Os tokens de mensagens estão disponíveis nos planos Pro e Agency.

Antes de começar

• Todos os planos têm acesso à API:
  • Nano: Email Verifier. Adicione um complemento Drive Storage para obter acesso completo à API e MCP do Drive.
  • Starter: acesso completo ao Drive e Email Verifier, além de acesso somente leitura às demais áreas de infraestrutura. Use o dashboard para essas ações de gravação.
  • Pro / Agency: acesso completo à API básica, incluindo tokens de mensagens. Os escopos White Label são adicionados enquanto a avaliação ou o complemento pago estiver ativo.
• Vai conectar um agente de IA? Adicione https://trekmail.net/mcp como servidor MCP remoto em qualquer cliente compatível. Se ele aceitar autorização pelo navegador, nenhum token manual será necessário. Consulte Conectar agentes de IA (MCP) para ver opções remotas, CLI/desktop, ponte e hospedagem própria.
• Vai criar sua própria integração? Crie um token tm_live_ em AI Agents & API → Tokens → Create token e envie-o como Authorization: Bearer …. Consulte Criar e gerenciar tokens de API.
• Ainda não conhece a API? Clique em Start tour na parte superior da página AI Agents & API para ver uma breve apresentação dos métodos de conexão, gerenciamento de tokens, aplicativos conectados e log de auditoria.

Como funciona a autenticação

Todas as solicitações devem incluir seu token no cabeçalho Authorization:

Authorization: Bearer tm_live_abc123...

Os tokens de operações começam com tm_live_ e os tokens de mensagens com tm_msg_. Ambos são exibidos uma única vez na criação e não podem ser mostrados novamente.

Se o token estiver ausente, revogado ou expirado, a API retornará 401 com o código de erro unauthenticated.

URL base e controle de versão

Todos os endpoints ficam em:

https://trekmail.net/api/v1

A URL base é exibida no dashboard AI Agents & API, em Quick Reference. A versão fica no caminho da URL. Se uma v2 for lançada algum dia, a v1 continuará funcionando.

Formato da resposta

As respostas bem-sucedidas retornam JSON com uma chave data para recursos individuais ou uma lista paginada:

{
  "data": [
    { "id": 1, "domain": "example.com", "status": "active" }
  ],
  "links": { "next": "...", "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

As respostas de erro seguem uma estrutura consistente:

{
  "error": {
    "code": "unauthenticated",
    "message": "Invalid or expired API token",
    "hint": "Check that your token is correct and has not been revoked.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

IDs de solicitação

Todas as respostas incluem um cabeçalho X-Request-Id. Você também pode enviar seu próprio valor por meio de X-Request-Id na solicitação. Ele será repetido na resposta e registrado na trilha de auditoria.

Limites de taxa

Cada token tem um limite por minuto. Quando você atinge o limite, a API retorna 429 com um cabeçalho Retry-After que indica quando tentar novamente.

As operações destrutivas (intenções de exclusão) têm um limite diário adicional por token e um intervalo entre exclusões consecutivas.

As operações de gravação de migração (iniciar, cancelar, tentar novamente) têm um limite dedicado de 10 solicitações por minuto e por token, além de um limite de simultaneidade em todo o servidor que retorna 503 quando muitas migrações estão em execução globalmente.

Os tokens de mensagens usam limites separados. Os padrões são 30 solicitações de leitura por minuto e por token, 60 solicitações de envio por minuto e por token, 5,000 leituras bem-sucedidas por dia e por token, e 100 envios por API por dia em uma caixa de correio. Um segundo contador de segurança para envio tem o padrão de 500 por token e por dia; normalmente o limite menor da caixa é aplicado primeiro. Essas proteções da API não substituem os limites do SMTP gerenciado do seu plano nem os limites próprios de um provedor externo.

Idempotência

Endpoints que alteram estado e são marcados como idempotentes exigem um cabeçalho Idempotency-Key. Isso abrange criações, atualizações, envios e exclusões em que uma repetição automática poderia duplicar o trabalho. Ações POST semelhantes a leitura, como detecção de provedor ou teste de conexão, não exigem a chave; consulte a tabela de endpoints ou a especificação OpenAPI. Se você enviar a mesma chave com o mesmo corpo, a API repetirá a resposta original sem criar duplicatas.

Idempotency-Key: create-mailbox-alice-2024

Se você enviar a mesma chave com um corpo diferente, a API retornará 409 Conflict.

Alocação de armazenamento da caixa de correio

Todos os endpoints que criam uma caixa de correio ou convite, POST /api/v1/mailboxes, /api/v1/mailboxes:bulk, /api/v1/mailboxes/invites, /api/v1/mailboxes/invites:bulk, aceitam um inteiro opcional storage_allocation_mb.

As alocações são validadas em relação ao pool ativo menos as caixas dedicadas existentes e os convites dedicados pendentes. Os endpoints em massa também validam a soma das alocações do lote e rejeitam o lote inteiro com 422 storage_pool_exceeded se ele exceder a capacidade. O pool é atualizado quando uma caixa dedicada é excluída, quando um convite é resgatado (a alocação passa para a nova caixa) e quando um convite pendente expira.

Nos convites, a alocação é registrada no código de acesso e copiada para a nova caixa no momento do resgate. Se o pool não comportar mais a alocação solicitada nesse momento (por exemplo, outro administrador aumentou sua alocação dedicada nesse intervalo), o resgate rebaixa de forma segura a nova caixa para o pool compartilhado em vez de falhar, e o destinatário vê um aviso na página de sucesso.

Acesso da caixa de correio ao Drive

Todas as caixas de correio têm um nível drive_access que determina quanto do Drive a pessoa pode acessar no webmail. Ele é retornado no recurso da caixa e pode ser definido com PATCH /api/v1/mailboxes/{id} ou, para várias caixas de uma vez, com POST /api/v1/mailboxes:drive-access.

O armazenamento é compartilhado em toda a conta, portanto este controle determina quanto desse pool uma única pessoa pode preencher com arquivos.

Suspensão do login da caixa de correio

O login de uma caixa de correio pode ser suspenso enquanto ela continua recebendo mensagens: webmail, IMAP, SMTP e senhas de dispositivos são recusados e as sessões abertas são encerradas, mas a entrega não é afetada. Nada é devolvido e tudo estará esperando quando o login for restaurado. Defina isso com POST /api/v1/mailboxes/{id}:suspend-login (e :resume-login) ou, para várias caixas, com POST /api/v1/mailboxes:login-access.

O recurso da caixa informa isso como login_suspended, login_suspended_at e login_suspended_reason. Consulte login_suspended para saber se a pessoa pode entrar e status para saber se a caixa está funcionando. Uma caixa suspensa permanece active, pois continua aceitando mensagens. :pause é diferente: ele define status como disabled e também interrompe a entrega.

Consulte Suspender o login da caixa de correio pela API.

O endpoint em massa aceita exatamente um seletor, mailbox_ids, domain_id ou all, e retorna o que fez:

{ "data": { "drive_access": "attachments_only", "matched": 24, "updated": 21, "skipped_shared": 3 } }

domain_id é o seletor indicado quando um domínio corresponde a um cliente. Caixas que já estão no nível solicitado contam como matched, mas não como updated, portanto é seguro repetir a chamada.

Caixas compartilhadas são recusadas no endpoint individual com 422 drive_access_not_applicable e ignoradas, mas contabilizadas, pelo endpoint em massa: elas não têm um usuário próprio de webmail, então os membros as abrem com seu próprio nível e um valor armazenado na linha compartilhada não mudaria nada.

A restrição se aplica tanto à API quanto à interface. O espaço do Drive de uma caixa restrita não aparece em GET /api/v1/drive/spaces, seus arquivos respondem 404 por id e não é possível criar um dispositivo de sincronização para ela.

Endereços de encaminhamento

GET /api/v1/domains/{id}/forwarding-addresses retorna mais do que a lista, porque dois aspectos de um endereço de encaminhamento não são visíveis no próprio endereço:

{
  "data": [ { "id": 8, "address": "sales@acme.com", "local_part": "sales",
              "domain_id": 4, "recipients": ["team@example.net"], "is_active": true } ],
  "limits": { "used": 1, "max": 100, "recipients_per_address": 15 },
  "delivery": { "active": true, "requires_plan": "pro",
                "paused_until": null, "paused_reason": null }
}

• limits.max é por domínio e depende do plano: 100 no Pro, 300 no Agency e 25 salvos, mas inativos, no Nano ou Starter.
• delivery.active indica se essas regras estão encaminhando mensagens agora. Ele é false em um plano abaixo de requires_plan e false enquanto paused_until estiver definido (a conta ultrapassou sua taxa de envio por hora; consulte Limites de envio por plano). Uma regra pode ter is_active: true e mesmo assim não entregar, portanto consulte delivery, e não apenas is_active, antes de informar que o encaminhamento funciona.

É permitido criar em um plano que não pode entregar, e a resposta é 201: a regra é armazenada e começa a funcionar após o upgrade. Isso corresponde ao dashboard, que mostra essas regras como salvas e inativas.

As rejeições são retornadas como 422, com error.code definido como validation_error ou limit_exceeded: um endereço já usado no domínio, um destinatário no mesmo domínio (o que causaria um loop), um domínio de destinatário sem MX funcional ou o limite por domínio esgotado.

POST e DELETE nesses endpoints exigem uma Idempotency-Key; PATCH não.

Histórico de entrega

GET /api/v1/domains/{id}/forwarding-addresses/{addressId}/log retorna o que realmente aconteceu com mensagens recentes, começando pela mais nova:

{
  "data": [
    { "id": 91, "occurred_at": "2026-07-27T09:12:04+00:00", "outcome": "delivered",
      "from": "rfq@northgatesupply.com", "to": "sales@example.net",
      "smtp_code": "2.0.0", "smtp_response": "250 2.0.0 OK" }
  ],
  "address": "sales@acme.com",
  "window": { "retention_days": 30, "max_events": 200 }
}

outcome pode ser delivered, deferred (falha temporária, ainda tentando novamente), failed (o servidor do destinatário rejeitou) ou blocked. O último significa que nosso filtro de spam interrompeu a mensagem antes do encaminhamento, portanto ela nunca chegou ao destinatário. Tratar blocked como devolução faria alguém investigar o servidor receptor por um problema ocorrido no nosso.

limit (1-200, padrão 100) é o único parâmetro. A janela corresponde à retenção do plano: 30 dias no Agency e 7 nos demais. Não há eventos mais antigos para consultar porque eventos encaminhados são removidos.

Caixas de correio compartilhadas (equipe)

Uma caixa de correio compartilhada é uma caixa de entrada de equipe, como support@ ou sales@, que os membros abrem pela própria conta normal no Webmail e, quando o acesso nativo está ativado, como uma pasta IMAP delegada. Não há senha compartilhada nem login separado. O acesso é uniforme: todos os membros podem ler, e um único sinalizador can_send controla se o membro pode responder como o endereço (true) ou tem acesso somente leitura (false). Não há funções de membros.

GET /api/v1/mailboxes e GET /api/v1/mailboxes/{id} agora retornam mailbox_type ("user" ou "shared") e o booleano is_shared; caixas compartilhadas também incluem shared_member_count. Use esses campos para distinguir uma caixa de equipe de uma normal antes de chamar os endpoints de membros.

Os endpoints de membros reutilizam seus escopos mailboxes:read / mailboxes:write existentes. Não há um escopo separado para caixas compartilhadas.

Para descobrir o acesso nativo em aplicativos de e-mail, chame GET /api/v1/mailboxes/{member_mailbox_id}/client-setup para a caixa normal de um membro. O objeto shared_mailboxes informa a disponibilidade nativa duradoura, a disponibilidade e o motivo efetivos de Send As, os caminhos exatos de Inbox/Sent/Archive/Junk e as operações permitidas. can_send é a permissão Can reply atribuída, não uma prova de que o SMTP esteja pronto. O endpoint nunca retorna uma senha. Chamá-lo com o id da caixa compartilhada retorna 422 direct_login_unavailable, pois o endereço compartilhado não pode se autenticar diretamente.

Remover um membro, alterar can_send ou converter uma caixa compartilhada em normal sincroniza as permissões do servidor de e-mail quando o acesso nativo está ativado. Uma resposta 503 native_access_sync_failed pode ser repetida e garante que a associação, a permissão ou o tipo de caixa permaneceu inalterado, em vez de aplicar parcialmente a operação.

Endpoints disponíveis

O Drive tem sua própria referência e não é repetido aqui; consulte a Visão geral da API do Drive. Os endpoints SMTP no nível da conta mantidos por compatibilidade com versões anteriores são descritos em Roteamento SMTP por domínio, em vez de serem listados como atuais.

Os endpoints da Cloudflare seguem o mesmo fluxo do dashboard: validar um token, listar zonas, conectar domínios, visualizar as alterações de DNS e aplicá-las. Tanto /cloudflare/preview quanto /cloudflare/apply aceitam dois controles opcionais por domínio:

• included_records, uma lista de permissões dos registros que podem ser alterados, organizada por ID de domínio: { "123": ["mx_primary", "spf_record"] }. Os registros omitidos são ignorados, portanto você pode aplicar somente MX e SPF e retornar ao DKIM depois. Omita o campo para aplicar todos os registros.
• confirmed_conflicts, quando a visualização identifica um registro que já existe com outro valor, inclua o ID desse registro aqui (no mesmo formato { domain_id: [record_ids] }) para autorizar a substituição.

Os IDs de registros (mx_primary, spf_record, dkim_primary, dmarc_main, …) vêm diretamente da resposta da visualização. Portanto, um agente típico solicita primeiro a visualização e envia para a aplicação os IDs desejados:

POST /api/v1/cloudflare/apply
{
  "domain_ids": [123],
  "included_records": { "123": ["mx_primary", "spf_record"] },
  "confirmed_conflicts": { "123": ["dmarc_main"] }
}

Roteamento SMTP por domínio e padrão da conta

O SMTP é configurado por domínio. Cada domínio escolhe uma de três rotas: envio gerenciado pela plataforma, um perfil SMTP salvo (seu próprio provedor, reutilizável entre domínios) ou "não configurado". Um único padrão para toda a conta decide com qual rota os novos domínios começam.

Endpoints por domínio (smtp:read / smtp:write):

Algumas observações sobre o corpo da rota:

• smtp_mode=platform seleciona o envio gerenciado; smtp_mode=profile exige smtp_connection_id; not_configured limpa a rota.
• smtp_mode=inherit faz o domínio acompanhar em tempo real o padrão da conta: sempre que o padrão muda, este domínio muda com ele. A interface web sempre grava rotas concretas, mas o backend ainda oferece suporte a inherit. Por isso, GET retorna effective_smtp_mode, mostrando o valor ao qual inherit corresponde no momento.
• set_account_default: true é o equivalente na API à opção Make this the account default do dashboard (novos domínios começam nesta rota). apply_to_all: true é o botão Apply to all domains (uma mudança única de todos os domínios para esta rota).

Endpoints do padrão para toda a conta (smtp:read / smtp:write):

Excluir um perfil que era o padrão da conta redefine o padrão para a base do plano.

Endpoints legados. Os endpoints GET/PUT /api/v1/smtp no nível da conta (e DELETE /api/v1/smtp/{id}, POST /api/v1/smtp:test, GET /api/v1/smtp:test-status/{jobId}) permanecem para compatibilidade com versões anteriores, mas não controlam mais o roteamento por domínio: use os endpoints por domínio e /smtp/default acima. As ferramentas MCP legadas get_smtp_config / update_smtp_config foram descontinuadas pelo mesmo motivo.

Branding White Label, clientes e acesso da equipe

O branding é configurado por domínio com branding:read / branding:write. Um domínio usa sua própria marca (mode=custom), herda o padrão da conta (mode=inherit) ou fica desativado. É necessário ter uma avaliação ativa ou um complemento pago do White Label. Após o cancelamento, o proprietário mantém acesso de recuperação somente leitura durante o período de carência exibido. Leia os dns_records do domínio e publique exatamente os registros retornados. Não derive nomes de host nem destinos CNAME de um exemplo.

PATCH é uma mesclagem parcial, portanto os campos omitidos são preservados. Se o branding estiver desativado, informe mode para reativá-lo. Um sender_email personalizado deve pertencer a um domínio com uma chave DKIM verificada. mail_zone_enabled fornece aplicativos de e-mail e sincronização DAV sob o domínio da própria marca. Ele pertence à marca, não a um único domínio, portanto exige mode=custom ou scope=account_default; um domínio inherit retorna 422 inherited_brand. Leia mail_zone.dns_status, mail_zone.client_hosts_status, mail_zone.records, mail_zone.dav_url e mail_zone.dav_ready para acompanhar o provisionamento e use apenas um endereço DAV pronto. Para conhecer o fluxo completo do agente, consulte o Guia de API e MCP de branding White Label.

A superfície White Label no nível da conta adiciona 13 rotas em /api/v1/white-label: status e progresso da configuração, um catálogo de acesso ativo, listagem e ações de ciclo de vida de membros, atividade da conta e histórico de ações e logins por membro. Ela usa members:read, members:write e activity:read. O acesso é sempre a interseção entre o direito da conta, a associação atual da pessoa, a concessão da credencial e qualquer restrição de domínio. Consulte Gerenciar equipes White Label com API e MCP para ver a tabela de rotas e as transições de estado.

A especificação OpenAPI está disponível em /api/openapi.json para importação no Postman, Insomnia ou em geradores de código.

Correções rápidas

• 401 "unauthenticated": verifique se o cabeçalho Authorization: Bearer <token> está presente e se o token não foi revogado nem expirou.
• 403 "plan_api_disabled": o escopo solicitado não está no seu plano. O Nano inclui o Email Verifier (e o Drive, caso você tenha comprado o complemento Drive Storage). Faça upgrade para o Starter ou superior para acessar o restante da API.
• 403 "token_scope_blocked_by_plan": seu token tem escopos que não estão disponíveis no plano atual. Revogue o token e crie um novo com os escopos permitidos.
• 403 "scope_blocked_by_entitlement": uma concessão White Label armazenada está indisponível porque o complemento está inativo ou a operação é uma gravação durante o período de carência. Reative o White Label e depois reemita ou reautorize a credencial.
• 403 "scope_blocked_by_membership": a função atual do membro é mais restrita do que a ação solicitada. Peça ao proprietário para alterá-la; somente reautorizar não pode ampliar a associação.
• 422 "missing_idempotency_key": adicione um cabeçalho Idempotency-Key à operação de gravação indicada pela referência do endpoint.
• 403 "mailbox_sending_paused": o envio por essa caixa de correio foi interrompido porque as mensagens enviadas deixaram de parecer pertencer ao proprietário, geralmente por causa de uma senha em mãos erradas. A leitura, a listagem e todos os outros endpoints continuam funcionando; apenas o envio é recusado, e tentar novamente não removerá o bloqueio. A senha da caixa de correio precisa ser alterada; depois disso, o suporte reativa o envio. Consulte Por que não consigo enviar e-mails?.
• 429 limite de taxa: aguarde o tempo indicado no cabeçalho Retry-After antes de tentar novamente.

Envio de e-mail: corpo, cabeçalhos e entregabilidade

POST /api/v1/messages/send recebe a estrutura de solicitação {to, subject, body: {text, html}, attachments, reply_to_message_id, headers}.

• body.text e body.html são opcionais, mas pelo menos um deles é obrigatório. Se você fornecer apenas body.text, geramos automaticamente uma alternativa em HTML usando parágrafos <p> (linhas em branco separam parágrafos; quebras de linha únicas se tornam <br>), para que a mensagem seja exibida como um e-mail comum em todos os clientes modernos. Se precisar de texto monoespaçado, envie o literal <pre>...</pre> em body.html.
• headers é um objeto opcional de cabeçalhos de saída fornecidos pelo usuário. A lista permitida é List-Unsubscribe, List-Unsubscribe-Post, Reply-To e qualquer cabeçalho personalizado de rastreamento X-*. Outros nomes (From, Subject, Message-Id, Authentication-Results etc.) são gerenciados pela plataforma e rejeitados com 422. Valores que contêm CR/LF também são rejeitados (proteção contra injeção de cabeçalho). Os valores são limitados a 998 caracteres de acordo com a RFC 2822.
• Para casos de envio em massa ou automação, consulte a seção Cabeçalhos de entregabilidade para remetentes em massa para configurar List-Unsubscribe e a opção auto_list_unsubscribe em toda a conta.