Mailboxes

Start a mailbox import

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.

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)

Path parameters

idstring required

Mailbox ID.

Headers

X-Shipmail-Organizationstring

OAuth access tokens only. The organization ID this request acts on. Required when the OAuth connection was approved for several organizations (400 validation_error without it); optional with one. An organization the connection was not approved for returns 403 authorization_error. Ignored for API keys, which belong to one organization.

Request body

Response

Import started.

object'import' required
idstring required
mailbox_idstring 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_addressstring 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_detailstring nullable required
errorstring nullable required
resume_atstring date-time nullable required
created_atstring date-time required
started_atstring date-time nullable required
completed_atstring date-time nullable required

Example response

{
  "id": "imp_abc123"
}

Changes

No recorded changes to this operation across all 1 revision of this API.