Visão geral da API do TrekMail Drive para desenvolvedores

A API do TrekMail Drive permite que aplicativos confiáveis e agentes de IA trabalhem com o mesmo armazenamento de arquivos exibido no painel e no webmail. Use-a para listar pastas, enviar arquivos, gerar links públicos de download, restaurar itens da lixeira, auditar o uso do armazenamento e automatizar fluxos de arquivos repetitivos sem dar ao agente acesso à conta inteira.

A automação do Drive faz parte da API REST v1 do TrekMail. Ela usa tokens bearer, respostas JSON, proteção de idempotência quando o endpoint oferece suporte e a mesma trilha de auditoria exibida em Agentes de IA e API → Log de auditoria. O modelo de permissões do Drive tem 11 escopos, incluindo escopos separados para senhas de dispositivos de sincronização. Os catálogos de endpoints e ferramentas MCP evoluem, portanto use a lista de ferramentas retornada e as respostas da API para conhecer a superfície atual disponível ao seu token.

O que você pode automatizar

As tarefas comuns da API do Drive incluem:

• Enviar relatórios mensais ao Drive da conta.
• Criar uma pasta para o cliente, adicionar arquivos e compartilhar um link de download.
• Permitir que um agente pesquise espaços de Drive de caixas de correio e resuma as alterações.
• Mover arquivos antigos para uma pasta de arquivo.
• Restaurar arquivos da lixeira após uma limpeza acidental.
• Consultar o status do complemento do Drive antes de avisar que o armazenamento do usuário está quase cheio.

A API é deliberadamente voltada para arquivos. Ela não substitui o painel de faturamento nem oferece alterações de pagamento ou assinatura.

Drive da conta e Drive da caixa de correio

O Drive tem duas superfícies de armazenamento. O Drive da conta é o espaço compartilhado da empresa. Em geral, é o lugar para recursos da marca, contratos, material de integração e pastas da equipe. O Drive da caixa de correio é o armazenamento pessoal associado a uma caixa dentro do webmail.

As solicitações da API identificam o destino com um parâmetro space:

account       # Account Drive
mailbox:42    # mailbox-personal Drive for mailbox ID 42
123           # internal Drive space ID, if your integration stores it

Os tokens podem ser limitados a caixas de correio específicas. Se um token estiver limitado à caixa 42, as solicitações para a caixa 99 retornarão uma resposta semelhante a "não encontrado", em vez de revelar que a outra caixa existe.

Autenticação e URL base

Use um token de operações no cabeçalho Authorization:

Authorization: Bearer tm_live_your_token

Os endpoints do Drive ficam em:

https://trekmail.net/api/v1/drive

Crie tokens em Agentes de IA e API → Tokens. Escolha apenas os escopos do Drive necessários ao seu fluxo de trabalho.

Os onze escopos do Drive

Uploads e arquivos grandes

Os uploads usam um padrão de duas etapas. Primeiro, a API reserva cota e retorna instruções de upload. Em seguida, seu cliente envia os bytes do arquivo para a URL de upload. Por fim, a API marca o upload como concluído. Arquivos grandes podem usar upload multipartes e atualizar as URLs das partes se uma transferência longa expirar.

Para a maioria dos agentes de IA, a ferramenta MCP drive_file_upload é mais simples do que chamar diretamente endpoints de upload de baixo nível. Ela cuida da detecção do tamanho, upload, conclusão e cancelamento em caso de falha em um único comando.

Links de compartilhamento

Os links de compartilhamento criam URLs públicas de download para arquivos individuais. São úteis quando um arquivo é grande demais para e-mail ou quando o acesso precisa ser revogável. Sempre que possível, defina uma data de validade e um limite de downloads. O token bruto do link é retornado apenas uma vez, na criação, portanto armazene imediatamente a URL retornada se o fluxo precisar dela.

Segurança na exclusão

As operações normais de exclusão enviam arquivos e pastas à lixeira. Os itens permanecem recuperáveis até serem restaurados, excluídos permanentemente ou removidos pelas regras de retenção do produto. Operações de exclusão permanente exigem escopos próprios e devem ficar isoladas em um token separado.

Limite do complemento do Drive

Os agentes podem consultar o status, o preço e a prévia de cancelamento do complemento do Drive com drive:addon:read. A compra, a alteração de tamanho ou o cancelamento do complemento do Drive não estão disponíveis por ferramentas de escrita REST ou MCP. Essas ações permanecem no painel para que o faturamento do armazenamento continue sendo um fluxo deliberado e controlado pelo usuário.