Gerenciar migrações de email pela API

A API de Migração permite importar emails de qualquer provedor IMAP para uma caixa de correio TrekMail por meio de uma integração ou agente. Você pode testar conexões, iniciar importações, monitorar o progresso por pasta, cancelar tarefas em execução, repetir falhas e limpar registros antigos.

Antes de começar

• Você precisa do plano Starter ou superior. O plano Nano não inclui a ferramenta de migração.
• Pro e Agency podem iniciar, cancelar, repetir e excluir migrações pela API (migrations:read + migrations:write). Starter pode ler migrações pela API e executar novas pelo painel.
• Uma migração pode ser executada por conta de cada vez. Inicie outra após o término da atual ou cancele-a primeiro.

Escopos

Endpoints

Testar conexão

POST /api/v1/migrations/test-connection
Scope: migrations:write

Valida as credenciais IMAP e retorna as pastas de origem com suas contagens de mensagens. Use antes de iniciar uma migração para confirmar a conexão e permitir que o usuário escolha as pastas a importar.

Corpo da solicitação:

Resposta (sucesso):

{
  "success": true,
  "folders": {
    "INBOX": 1234,
    "Sent": 567,
    "Drafts": 12,
    "Work": 89
  }
}

Resposta (falha): 422 com o código de erro connection_failed.

Listar migrações

GET /api/v1/migrations
Scope: migrations:read

Retorna uma lista paginada das tarefas de migração da sua conta.

Parâmetros de consulta:

Obter migração

GET /api/v1/migrations/{id}
Scope: migrations:read

Retorna o status detalhado da migração, incluindo o progresso por pasta.

Resposta:

{
  "data": {
    "id": 5,
    "mailbox_id": 10,
    "mailbox_email": "support@acme.com",
    "provider": "gmail",
    "source_host": "imap.gmail.com",
    "source_email": "j***e@gmail.com",
    "status": "processing",
    "progress": 45,
    "total_messages": 1234,
    "imported_messages": 556,
    "failed_messages": 2,
    "skipped_duplicates": 12,
    "selected_folders": ["INBOX", "Sent"],
    "import_since": "2025-01-01",
    "skip_duplicates": true,
    "folders": [
      { "name": "INBOX", "status": "processing", "expected": 1000, "imported": 450, "failed": 2, "skipped": 10 },
      { "name": "Sent", "status": "pending", "expected": 234, "imported": 0, "failed": 0, "skipped": 0 }
    ],
    "error_message": null,
    "poll_hint_seconds": 10,
    "started_at": "2026-03-13T10:00:00+00:00",
    "finished_at": null,
    "created_at": "2026-03-13T09:59:50+00:00"
  }
}

poll_hint_seconds informa a frequência de consulta: 5 segundos durante pending/validating/planning, 10 segundos durante processing e null nos estados finais.

source_email é mascarado por segurança (por exemplo, j***e@gmail.com).

Iniciar migração

POST /api/v1/migrations
Scope: migrations:write

Inicia uma nova migração de email. Somente uma migração pode ser executada por conta de cada vez.

Corpo da solicitação:

Resposta: 201 com o recurso da tarefa de migração.

Respostas de erro:

Cancelar migração

POST /api/v1/migrations/{id}:cancel
Scope: migrations:write

Cancela uma migração em execução. Ela deve estar em um estado ativo (pending, validating, planning ou processing).

Repetir migração

POST /api/v1/migrations/{id}:retry
Scope: migrations:write

Repete uma migração failed ou cancelled. Redefine o progresso como 0 e reinicia o processo de validação.

Retorna 409 se outra migração já estiver em execução na conta.

Migrações parciais

A TrekMail pode tentar continuar uma migração parcialmente concluída quando for seguro. Verifique o status antes de agir. Se ela não estiver mais progredindo, confira as credenciais e os limites da conta de origem e use o endpoint de repetição ou a ação Continuar do painel. Não suponha que uma importação parcial terminará sem verificar seu status final.

Excluir migração

DELETE /api/v1/migrations/{id}
Scope: migrations:write

Exclui um registro de migração. A migração não pode estar em execução (cancele-a primeiro).

Retorna 204 No Content em caso de sucesso.

Limites de taxa

As operações de gravação de migração têm um limite próprio de 10 solicitações por minuto por token, separado do limite padrão da API.

O servidor também aplica um limite global de simultaneidade (padrão: 20 migrações simultâneas). Quando ele é atingido, novas solicitações retornam 503 com migration_capacity_reached e retryable: true. Aguarde alguns minutos e tente novamente.

Eventos de auditoria

Todas as ações da API de migração são registradas no log de auditoria:

• migration_started: uma nova migração foi iniciada
• migration_cancelled: uma migração em execução foi cancelada
• migration_retried: uma migração com falha ou cancelada foi repetida
• migration_deleted: um registro de migração foi excluído

Ferramentas MCP

Os mesmos recursos estão disponíveis pelo servidor MCP, incluindo testar, listar, iniciar, cancelar, repetir, retomar, atualizar senhas e excluir migrações individuais e em massa. Um administrador MCP hospedado localmente pode exigir aprovação explícita para gravações de migração. Consulte Conectar agentes de IA (MCP) para obter detalhes.

API de migração em massa

A API de Migração em Massa permite migrar várias contas ao mesmo tempo com dados no formato CSV. Consulte Migração de email em massa para ver o guia e Formato CSV de migração em massa para conhecer o formato dos dados.

Endpoints

Solicitação de visualização

POST /api/v1/migrations/bulk/preview
Scope: migrations:write

A resposta inclui linhas categorizadas (valid, invalid_source_email, invalid_destination, etc.), limites do plano, estimativa de tempo e informações de armazenamento.

Solicitação para iniciar lote

POST /api/v1/migrations/bulk
Scope: migrations:write

Os mesmos campos da visualização, mais:

Limites de simultaneidade

O limite global do servidor (20 migrações simultâneas) é compartilhado entre migrações individuais e em massa.

Ferramentas MCP

As ferramentas MCP para migração em massa são preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration e update_bulk_migration_job_password. Um administrador MCP hospedado localmente pode exigir aprovação explícita para ações de gravação.

Soluções rápidas

• 403 "insufficient_scope": seu token precisa de migrations:read ou migrations:write. Crie outro token com os escopos corretos.
• 403 "token_scope_blocked_by_plan": os escopos de migração exigem um plano pago (Starter ou superior).
• 409 "active migration running": cancele a migração existente ou aguarde sua conclusão.
• 503 "migration_capacity_reached": o servidor está sem capacidade. Tente novamente em alguns minutos.
• 422 no teste de conexão: verifique credenciais IMAP, nome do host, porta e configuração de segurança.