---
title: "Start a mailbox import"
method: POST
path: "/mailboxes/{id}/imports"
tags: ["Mailboxes"]
---

# Start a mailbox import

`POST /mailboxes/{id}/imports`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/mailboxes/{id}/imports`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

Import mail from another provider into this mailbox. IMAP sources run over the source provider's IMAP with an app or device password. File sources import staged uploads (complete Google Takeout ZIPs or VCF files, Proton or Tuta EML exports, and generic MBOX or EML zips). File imports always import all dates, spam, and trash; file-source options are ignored. Google Takeout contacts embedded in the archive are imported automatically. The import runs in the background, preserves folders, read state, and dates, deduplicates, and can be re-run safely.

## Path parameters

- `id` string, required

## Headers

- `X-Shipmail-Organization` string

## Request body

- CreateMailboxImportRequest
  - `source` union, required
    - object
      - `type` 'imap', required
      - `provider` 'gmail' | 'yahoo' | 'aol' | 'icloud' | 'fastmail' | 'zoho' | 'titan' | 'namecheap' | 'migadu' | 'gmx' | 'mail_com' | 'mailbox_org' | 'mxroute' | 'infomaniak' | 'ovh' | 'gandi' | 'imap', required: Outlook imports require the dashboard's Sign in with Microsoft and cannot be started via the API.
      - `email` string, required
      - `password` string, required: App password, device password, or IMAP password. Encrypted at rest, used only for this import, and deleted when it finishes.
      - `host` string: Required for providers imap and mxroute. Optional for provider titan or ovh to override the default server.
      - `port` integer: 143 or 993. Defaults to 993.
    - object
      - `type` 'files', required
      - `provider` 'takeout' | 'proton' | 'tuta' | 'file', required
      - `file_ids` string[], required: File IDs from POST /mailboxes/{id}/imports/files, uploaded first.
  - `options` object: Selection options for IMAP sources. File imports ignore these values and always import every date, including spam and trash.
    - `folders` string[], nullable: Source folder paths to import. Null or omitted imports everything.
    - `range` 'all' | '12m' | '3m' | '1m'
    - `include_spam` boolean
    - `include_trash` boolean

## Response `201`

Import started.

- MailboxImport
  - `object` 'import', required
  - `id` string, required
  - `mailbox_id` string, required
  - `kind` 'imap' | 'file', required
  - `provider` 'gmail' | 'outlook' | 'yahoo' | 'aol' | 'icloud' | 'fastmail' | 'zoho' | 'titan' | 'namecheap' | 'migadu' | 'gmx' | 'mail_com' | 'mailbox_org' | 'mxroute' | 'infomaniak' | 'ovh' | 'gandi' | 'imap' | 'takeout' | 'proton' | 'tuta' | 'file', required
  - `source_address` string, nullable, required
  - `status` 'queued' | 'running' | 'paused_throttle' | 'paused_quota' | 'completed' | 'failed' | 'cancelled' | 'undo_queued' | 'undoing' | 'undone' | 'undo_failed', required: paused_throttle means the source provider's daily download limit was reached; the import resumes automatically at resume_at. paused_quota means the destination mailbox is out of storage.
  - `status_detail` string, nullable, required
  - `error` string, nullable, required
  - `resume_at` string, date-time, nullable, required
  - `counts` object, required
    - `found` integer, required
    - `imported` integer, required
    - `undone` integer, required
    - `duplicates_skipped` integer, required
    - `oversize_skipped` integer, required
    - `failed` integer, required
    - `contacts_imported` integer, required
  - `bytes` object, required
    - `total` integer, required
    - `imported` integer, required
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable, required
  - `completed_at` string, date-time, nullable, required
  - `folders` MailboxImportFolder[]: Per-folder progress. Returned by getMailboxImport only.
    - `source_folder` string, required
    - `target_folder` string, nullable, required
    - `role` string, nullable, required
    - `state` 'pending' | 'importing' | 'completed' | 'failed' | 'skipped', required: Transfer state of this source folder. "skipped" means the source server refused the folder; the import finished without it.
    - `found` integer, required
    - `imported` integer, required
    - `duplicates` integer, required
    - `oversize` integer, required
    - `failed` integer, required
  - `source_retention` MailboxImportSourceRetention
    - `state` 'available' | 'missing' | 'expired' | 'deleted' | 'not_applicable', required
    - `expires_at` string, date-time, nullable, required
    - `deleted_at` string, date-time, nullable, required

## Other responses

- `404`: Resource not found.
- `409`: An import is already running for this mailbox.
- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)