API로 이메일 마이그레이션 관리하기

Migration API를 사용하면 통합 또는 에이전트를 통해 모든 IMAP 제공업체의 이메일을 TrekMail 사서함으로 가져올 수 있습니다. 연결을 테스트하고, 가져오기를 시작하고, 폴더별 진행 상황을 모니터링하고, 실행 중인 작업을 취소하고, 실패한 작업을 재시도하고, 오래된 레코드를 정리할 수 있습니다.

시작하기 전에

• Starter 이상의 요금제가 필요합니다. Nano 요금제에는 마이그레이션 도구가 포함되지 않습니다.
• Pro와 Agency에서는 API를 통해 마이그레이션을 시작, 취소, 재시도 및 삭제할 수 있습니다(migrations:read + migrations:write). Starter에서는 API로 마이그레이션을 읽고 대시보드에서 새 마이그레이션을 실행할 수 있습니다.
• 계정마다 한 번에 하나의 마이그레이션만 실행할 수 있습니다. 현재 마이그레이션이 끝난 후 새 마이그레이션을 시작하거나 먼저 현재 마이그레이션을 취소하세요.

범위

엔드포인트

연결 테스트

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

IMAP 자격 증명을 검증하고 메시지 수가 포함된 원본 폴더 목록을 반환합니다. 마이그레이션을 시작하기 전에 이를 사용하여 연결이 작동하는지 확인하고 사용자가 가져올 폴더를 선택하도록 하세요.

요청 본문:

응답(성공):

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

응답(실패): 422 및 connection_failed 오류 코드.

마이그레이션 목록

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

계정의 마이그레이션 작업을 페이지가 매겨진 목록으로 반환합니다.

쿼리 매개변수:

마이그레이션 가져오기

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

폴더별 진행 상황 분석을 포함한 자세한 마이그레이션 상태를 반환합니다.

응답:

{
  "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**는 업데이트를 폴링할 빈도를 알려 줍니다. pending/validating/planning 중에는 5초, processing 중에는 10초, 종료 상태에서는 null입니다.

**source_email**은 보안을 위해 마스킹됩니다(예: j***e@gmail.com).

마이그레이션 시작

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

새 이메일 마이그레이션을 시작합니다. 계정마다 한 번에 하나의 마이그레이션만 실행할 수 있습니다.

요청 본문:

응답: 마이그레이션 작업 리소스와 함께 201 반환.

오류 응답:

마이그레이션 취소

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

실행 중인 마이그레이션을 취소합니다. 마이그레이션은 활성 상태(pending, validating, planning 또는 processing)여야 합니다.

마이그레이션 재시도

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

failed 또는 cancelled 마이그레이션을 재시도합니다. 진행률을 0으로 재설정하고 검증 파이프라인에 다시 진입합니다.

계정에서 다른 마이그레이션이 이미 실행 중이면 409를 반환합니다.

부분 마이그레이션

안전한 경우 TrekMail은 부분적으로 완료된 마이그레이션을 계속하려고 할 수 있습니다. 작업을 수행하기 전에 마이그레이션 상태를 확인하세요. 더 이상 진행되지 않으면 원본 계정 자격 증명과 한도를 검토한 후 재시도 엔드포인트 또는 대시보드의 계속 작업을 사용하세요. 최종 상태를 확인하지 않은 채 부분 가져오기가 완료될 것으로 가정하지 마세요.

마이그레이션 삭제

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

마이그레이션 레코드를 삭제합니다. 마이그레이션이 실행 중이면 안 됩니다(먼저 취소하세요).

성공하면 204 No Content를 반환합니다.

속도 제한

마이그레이션 쓰기 작업에는 표준 API 속도 제한과 별도로 토큰당 분당 10개 요청이라는 전용 속도 제한이 적용됩니다.

또한 서버는 전역 동시 실행 한도(기본값: 동시 마이그레이션 20개)를 적용합니다. 한도에 도달하면 새 마이그레이션 요청은 503과 함께 migration_capacity_reached 및 retryable: true를 반환합니다. 몇 분 후 다시 시도하세요.

감사 이벤트

모든 마이그레이션 API 작업은 감사 로그에 기록됩니다.

• migration_started: 새 마이그레이션이 시작됨
• migration_cancelled: 실행 중인 마이그레이션이 취소됨
• migration_retried: 실패하거나 취소된 마이그레이션이 재시도됨
• migration_deleted: 마이그레이션 레코드가 삭제됨

MCP 도구

단일 및 대량 마이그레이션을 테스트, 나열, 시작, 취소, 재시도, 재개하고 비밀번호를 업데이트하거나 삭제하는 작업을 포함하여 동일한 마이그레이션 기능을 MCP 서버에서 사용할 수 있습니다. 로컬에서 호스팅하는 MCP 관리자는 마이그레이션 쓰기에 명시적 승인을 요구할 수 있습니다. 자세한 내용은 AI 에이전트 연결(MCP)을 참조하세요.

대량 마이그레이션 API

대량 마이그레이션 API를 사용하면 CSV 형식의 데이터 페이로드로 여러 계정을 한 번에 마이그레이션할 수 있습니다. 사용자 가이드는 대량 이메일 마이그레이션을, 데이터 형식은 대량 마이그레이션 CSV 형식을 참조하세요.

엔드포인트

미리 보기 요청

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

응답에는 분류된 행(valid, invalid_source_email, invalid_destination 등), 요금제 한도, 예상 시간 및 저장 공간 정보가 포함됩니다.

배치 시작 요청

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

미리 보기와 같은 필드에 다음이 추가됩니다.

동시 실행 한도

전역 서버 한도(동시 마이그레이션 20개)는 단일 마이그레이션과 대량 마이그레이션이 공유합니다.

MCP 도구

대량 마이그레이션 MCP 도구는 preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration, update_bulk_migration_job_password입니다. 로컬에서 호스팅하는 MCP 관리자는 쓰기 작업에 명시적 승인을 요구할 수 있습니다.

빠른 해결 방법

• 403 "insufficient_scope": 토큰에 migrations:read 또는 migrations:write가 필요합니다. 올바른 범위로 새 토큰을 만드세요.
• 403 "token_scope_blocked_by_plan": 마이그레이션 범위에는 유료 요금제(Starter 이상)가 필요합니다.
• 409 "active migration running": 기존 마이그레이션을 취소하거나 완료될 때까지 기다리세요.
• 503 "migration_capacity_reached": 서버 용량이 가득 찼습니다. 몇 분 후 다시 시도하세요.
• test-connection의 422: IMAP 자격 증명, 호스트 이름, 포트 및 보안 설정을 확인하세요.