Managing Email Migrations via the API

The Migration API lets you import email from any IMAP provider into a TrekMail mailbox through an integration or agent. You can test connections, start imports, monitor per-folder progress, cancel running jobs, retry failures, and clean up old records.

Before you start

• You need a Starter plan or higher. The Nano plan does not include the migration tool.
• Pro and Agency can start, cancel, retry, and delete migrations through the API (migrations:read + migrations:write). Starter can read migrations via the API and run new ones from the dashboard.
• One migration can run per account at a time. Start a new one after the current one finishes or cancel it first.

Scopes

Endpoints

Test connection

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

Validates IMAP credentials and returns a list of source folders with message counts. Use this before starting a migration to verify the connection works and let the user choose which folders to import.

Request body:

Response (success):

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

Response (failure): 422 with connection_failed error code.

List migrations

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

Returns a paginated list of migration jobs for your account.

Query parameters:

Get migration

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

Returns detailed migration status including per-folder progress breakdown.

Response:

{
  "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 tells you how often to poll for updates: 5 seconds during pending/validating/planning, 10 seconds during processing, null for terminal states.

source_email is masked for security (e.g., j***e@gmail.com).

Start migration

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

Starts a new email migration. Only one migration can run per account at a time.

Request body:

Response: 201 with the migration job resource.

Error responses:

Cancel migration

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

Cancels a running migration. The migration must be in an active state (pending, validating, planning, or processing).

Retry migration

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

Retries a failed or cancelled migration. Resets progress to 0 and re-enters the validation pipeline.

Returns 409 if another migration is already running on the account.

Partial migrations

TrekMail may try to continue a partially completed migration when it is safe to do so. Check the migration status before taking action. If it is no longer progressing, review the source account credentials and limits, then use the retry endpoint or the dashboard's Continue action. Do not assume a partial import will complete without checking its final status.

Delete migration

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

Deletes a migration record. The migration must not be running (cancel it first).

Returns 204 No Content on success.

Rate limits

Migration write operations have a dedicated rate limit of 10 requests per minute per token, separate from the standard API rate limit.

Additionally, the server enforces a global concurrency limit (default: 20 simultaneous migrations). When the limit is reached, new migration requests return 503 with migration_capacity_reached and retryable: true. Wait a few minutes and retry.

Audit events

All migration API actions are recorded in the audit log:

• migration_started: a new migration was initiated
• migration_cancelled: a running migration was cancelled
• migration_retried: a failed or cancelled migration was retried
• migration_deleted: a migration record was deleted

MCP tools

The same migration capabilities are available through the MCP server, including test, list, start, cancel, retry, resume, password-update, and delete actions for single and bulk migrations. A locally hosted MCP administrator can require explicit approval for migration writes. See Connecting AI Agents (MCP) for details.

Bulk Migration API

The Bulk Migration API lets you migrate many accounts at once using a CSV-style data payload. See Bulk Email Migration for the user guide and Bulk Migration CSV Format for the data format.

Endpoints

Preview request

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

Response includes categorized rows (valid, invalid_source_email, invalid_destination, etc.), plan limits, time estimate, and storage info.

Start batch request

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

Same fields as preview, plus:

List batches response

GET /api/v1/migrations/bulk is paginated and follows the standard envelope described in API Overview — batches in data, paging in links and meta. Add status to filter and per_page (1-100, default 20) to size the page.

{
  "data": [
    { "id": 42, "name": "Acme cutover", "status": "completed",
      "total_jobs": 120, "completed_jobs": 118, "failed_jobs": 2,
      "progress_pct": 100, "poll_hint_seconds": null,
      "summary": { "total_messages_imported": 481203, "total_messages_failed": 17, "total_skipped_duplicates": 2904 },
      "started_at": "2026-07-27T09:12:04+00:00", "finished_at": "2026-07-27T14:48:51+00:00" }
  ],
  "links": { "next": null, "prev": null },
  "meta": { "current_page": 1, "last_page": 1, "total": 1 }
}

poll_hint_seconds tells you how long to wait before asking again: 5 while a batch is processing, 30 while it is queued or paused, and null once it has finished.

Concurrency limits

The global server limit (20 concurrent migrations) is shared between single and bulk migrations.

MCP tools

Bulk migration MCP tools are preview_bulk_migration, start_bulk_migration, list_bulk_migrations, get_bulk_migration, cancel_bulk_migration, retry_bulk_migration, resume_bulk_migration, delete_bulk_migration, and update_bulk_migration_job_password. A locally hosted MCP administrator can require explicit approval for write actions.

Quick fixes

• 403 "insufficient_scope": Your token needs migrations:read or migrations:write. Create a new token with the correct scopes.
• 403 "token_scope_blocked_by_plan": Migration scopes require a paid plan (Starter or higher).
• 409 "active migration running": Cancel the existing migration or wait for it to finish.
• 503 "migration_capacity_reached": The server is at capacity. Retry in a few minutes.
• 422 on test-connection: Check your IMAP credentials, hostname, port, and security setting.