Управление миграциями почты через API

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 указывает частоту проверки обновлений: 5 секунд в состояниях pending/validating/planning, 10 секунд в состоянии processing, 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.

Ограничения частоты запросов

Для операций записи миграций действует отдельное ограничение частоты: 10 запросов в минуту на токен, независимо от стандартного ограничения частоты API.

Кроме того, сервер применяет глобальное ограничение параллельного выполнения (по умолчанию: 20 одновременных миграций). При достижении лимита новые запросы миграции возвращают 503 с migration_capacity_reached и retryable: true. Подождите несколько минут и повторите попытку.

События аудита

Все действия API миграций записываются в журнал аудита:

• migration_started: запущена новая миграция
• migration_cancelled: выполняемая миграция отменена
• migration_retried: повторно запущена миграция с ошибкой или отменённая миграция
• migration_deleted: запись миграции удалена

Инструменты MCP

Те же возможности миграции доступны через сервер MCP, включая проверку, получение списка, запуск, отмену, повтор, возобновление, обновление пароля и удаление отдельных и массовых миграций. Администратор локально размещённого MCP может требовать явного подтверждения операций записи миграций. Подробнее см. в статье Подключение агентов ИИ (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": сервер достиг предельной нагрузки. Повторите попытку через несколько минут.
• 422 при test-connection: проверьте учётные данные IMAP, имя хоста, порт и настройку безопасности.

Связанные статьи

• Обзор API
• Обзор импорта почты
• Области API и разрешения тарифов
• Меры безопасности и намерения удаления
• Подключение агентов ИИ (MCP)