> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oximail.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration

> Importing mail, contacts, calendars, and tasks into OxiMail: the oximail migrate sources (IMAP, Stalwart, mbox/Maildir, Google Takeout, vCard, iCalendar), idempotence, and the post-import checks.

`oximail migrate` imports existing data into a provisioned account. The [setup wizard](../first-boot) offers it as its final step, and it can be run standalone any number of times — the import is resumable and keeps its own progress state, so a re-run continues instead of duplicating.

## Sources

| Flag                            | Source                                                                                                     |
| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--from-imap <host>`            | Any live IMAP4 server (Dovecot, Exchange, Gmail, …). Mail and folder structure.                            |
| `--from-jmap <url> --token <t>` | A live Stalwart server over its JMAP API.                                                                  |
| `--from-dump <path>`            | An exported Stalwart data dump directory (offline migration).                                              |
| `--from-mbox <path>`            | An mbox file or a Maildir directory.                                                                       |
| `--from-google-takeout <path>`  | A Google Takeout export — auto-detects the `Mail/`, `Contacts/`, `Calendar/`, and `Tasks/` subdirectories. |
| `--from-vcf <path>`             | A vCard file (3.0 or 4.0, multiple entries per file) — contacts only.                                      |
| `--from-ics <path>`             | An iCalendar file — `VEVENT` (events) and `VTODO` (tasks).                                                 |

## What the import gets right

* **Folder roles are detected from names.** A localized source folder with no role metadata ("Brouillons", "Papierkorb", "Sent Items", …) merges into the matching provisioned system folder through a multilingual name→role table, instead of arriving as a duplicate custom folder next to an empty system one. This applies in every mode, including JMAP-mode imports.
* **Recurring events become real recurrence rules.** Common client `RRULE`s are converted into typed JMAP `RecurrenceRules` through the same conversion authority the live server uses. An unconvertible residual is kept **verbatim** (and the event is flagged `hasUnmodeledRecurrence` on read) with a loud warning — never a half-converted rule, never a silent drop.
* **Directory identities are minted fresh.** Imported accounts get new, distinct principal ids (the account↔principal binding is an internal column, not id equality), matching what the runtime does for natively created accounts.
* **Everything lands through the normal ingestion path.** Imported mail is parsed, indexed, threaded, and encrypted at rest exactly like delivered mail; there is no separate "imported" storage class.

## Idempotence and the state sidecar

The migration records per-account progress in a state sidecar, so an interrupted run resumes and a completed account is skipped on re-run. Deleting an account — by CLI **or** by the admin API — purges its migration state, so a delete followed by a re-migration imports it again rather than silently skipping it as "already migrated".

## After the import

Run the two dry-run-by-default repair commands and the DNS check:

```bash theme={null}
oximail account dedupe-folders --all-accounts        # duplicate folders from older imports
oximail account dedupe-tasks   --all-accounts        # exact-duplicate task rows from repeated imports
oximail check-dns --domain <domain> --ip <ip>        # the domain's mail DNS
```

Both `dedupe` commands print their plan without touching anything; add `--apply` to execute. See [Groupware](./groupware#repair-one-shots) for what exactly they repair, and the [CLI reference](./cli) for all flags.

<Note>
  Accounts must exist before mail can be imported into them — create them with `oximail account create` (or the wizard) first. The import authenticates against the **source**; it never needs the users' OxiMail passwords.
</Note>