# Organization API: Customer Portal: Migrations

> The 6 Organization API operations for migrations.

Source: https://www.coritan.com/docs/api/reference/organizations/customer-portal/mail-migrations/

Part of [Customer Portal](/docs/api/reference/organizations/customer-portal/).

## Operations

| Method | Path | Summary |
| --- | --- | --- |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-migrations) | List the service's migrations |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/cpanel`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-cpanel) | Move a cPanel account's mail here |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/cpanel/discover`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-cpanel-discover) | Find what a cPanel account holds and what moving it here would do |
| GET | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}`](#op-get-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id) | Get one migration and how far each of its mailboxes has got |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}/finish`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id-finish) | Finish a migration and forget the old mailboxes' passwords |
| POST | [`/api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}/sync`](#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id-sync) | Bring in what reached the old mailboxes since the migration started |

### List the service's migrations {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-migrations}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations`

List the service's migrations.

The last 20, newest first, each with every mailbox's latest import
and the totals.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Move a cPanel account's mail here {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-cpanel}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/cpanel`

Move a cPanel account's mail here.

Nothing changes until every check
holds: the account answers, the plan has room for the new mailboxes
and their quotas, the old server's IMAP answers over TLS on port 993,
and each old mailbox password given signs in. Then each new mailbox is
made with a new password, returned once in `passwords`; forwarders to
mailboxes here become aliases; and an import starts into each mailbox
from the old server. With `reset_passwords`, an old mailbox given no
password gets a new one on the old server, so mail apps signed in
there stop working. Answers `422` with `migration_invalid`,
`plan_full`, `plan_storage`, `imap_unreachable` or `source_refused`
and changes nothing, and `429` after 10 migrations or syncs in a day.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `host` | string | yes | The cPanel host, such as `example.com`, `example.com:2083` or the server name the host gave you |
| `username` | string | yes | The cPanel username, the one cPanel shows as its current user |
| `token` | string or null | no | An API token made in cPanel under Security, Manage API Tokens. Needed for an account with two-factor sign-in |
| `password` | string or null | no | The cPanel account's password, when there is no token |
| `mailboxes` | array of CpanelMailboxChoice or null | no | The old mailboxes to move. Leave it out to move every one that can |
| `mailboxes[].address` | string | yes | The old mailbox's address, as discovery listed it |
| `mailboxes[].import` | boolean | no | Whether to bring its mail. False makes the mailbox here and leaves its mail behind |
| `mailboxes[].password` | string or null | no | The old mailbox's current password, to read it without changing anything on the old server |
| `mailboxes[].quota_bytes` | integer or null | no | The new mailbox's quota. Defaults to the size discovery suggested |
| `reset_passwords` | boolean | no | Whether we may set a new password on each old mailbox that has no `password` here, to read its mail |
| `forwarders` | boolean | no | Whether to make an alias for each forwarder that sends only to mailboxes on this service |
| `catch_all` | boolean | no | Whether to make a catch-all for a domain whose default address is one of the mailboxes |
| `trash` | boolean | no | Whether to bring the old Trash folders |
| `spam` | boolean | no | Whether to bring the old Spam folders |

#### Responses

| Status | Meaning |
| --- | --- |
| `201` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Find what a cPanel account holds and what moving it here would do {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-cpanel-discover}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/cpanel/discover`

Find what a cPanel account holds and what moving it here would do.

Signs in to the account's cPanel API and changes nothing: each email
account, with how much it holds and whether it becomes a new mailbox,
goes into one already here, or cannot move yet and why; each forwarder
and whether it becomes an alias; each domain's default address; the
autoresponders; and whether the plan has room. Sign in with an API
token, or with the cPanel password when the account has no two-factor
sign-in. Answers `422` with `cpanel_refused`, `cpanel_unreachable` or
`cpanel_empty` when the account cannot be read, and `429` after 30
tries in an hour.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Request body

`application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `host` | string | yes | The cPanel host, such as `example.com`, `example.com:2083` or the server name the host gave you |
| `username` | string | yes | The cPanel username, the one cPanel shows as its current user |
| `token` | string or null | no | An API token made in cPanel under Security, Manage API Tokens. Needed for an account with two-factor sign-in |
| `password` | string or null | no | The cPanel account's password, when there is no token |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Get one migration and how far each of its mailboxes has got {#op-get-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id}

`GET /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}`

Get one migration and how far each of its mailboxes has got.

Where its mail came from, each mailbox with its latest import, the
aliases made and what did not move, and whether it still keeps the
old mailboxes' passwords for another pass.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `migration_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Finish a migration and forget the old mailboxes' passwords {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id-finish}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}/finish`

Finish a migration and forget the old mailboxes' passwords.

The migration keeps them for another pass until then. Imports under
way go on to the end. We forget them 30 days after the migration
started in any case.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `migration_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |

### Bring in what reached the old mailboxes since the migration started {#op-post-api-v1-orgs-org-slug-portal-mail-service-id-migrations-migration-id-sync}

`POST /api/v1/orgs/{org_slug}/portal/mail/{service_id}/migrations/{migration_id}/sync`

Bring in what reached the old mailboxes since the migration started.

Run it once the domain's MX records point here. A paused import goes
on, one under way is left alone, and any other starts again from the
kept password. Messages already brought are not brought twice.
Answers `409` `migration_finished` once the passwords are forgotten.

#### Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `migration_id` | path | integer | yes |
| `org_slug` | path | string | yes |
| `service_id` | path | integer | yes |

#### Responses

| Status | Meaning |
| --- | --- |
| `200` | Success. |
| `422` | The request is not valid. `detail` lists each problem. |