---
title: "nextmail connected-mailboxes"
description: "Every command in this namespace, with its arguments, flags and examples."
url: "https://nextmail.sh/docs/cli/reference/connected-mailboxes"
area: "CLI"
category: "Reference"
---

# nextmail connected-mailboxes

Every command in this namespace, with its arguments, flags and examples.

## Commands

### `nextmail connected-mailboxes list`

List the connected mailboxes

```bash
nextmail connected-mailboxes list [flags]
```

Resolves every mailbox connected to the workspace in one array, newest first. The list comes whole and is never paged. A connected mailbox stays at its provider, such as Gmail or Yahoo, and is worked from Nextmail: its new mail is copied in, what is done to it here goes back to the provider, and mail written as its address is sent through the provider.

`status` is `active` while it syncs and sends, `paused` while a person stopped it, `needs-sign-in` when the provider stopped accepting its password, and `failing` when the last five syncs failed and it keeps trying less often.

- Scopes: `threads:read`.
- Needs a sign-in.
- Aliases: `ls`.

**Examples**

```bash
nextmail connected-mailboxes list
```

Print the raw JSON

```bash
nextmail connected-mailboxes list --json
```

Also available in: API [`GET /connected-mailboxes`](https://nextmail.sh/docs/api/reference/connected-mailboxes#get-connected-mailboxes); TypeScript [`nextmail.connectedMailboxes.list()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#list); Python [`connected_mailboxes.list()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#list); Ruby [`connected_mailboxes.list`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#list); PHP [`connectedMailboxes->list`](https://nextmail.sh/docs/php/reference/connected-mailboxes#list); Go [`ConnectedMailboxes.List`](https://nextmail.sh/docs/go/reference/connected-mailboxes#list); Java [`connectedMailboxes().list`](https://nextmail.sh/docs/java/reference/connected-mailboxes#list); C# [`ConnectedMailboxes.ListAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#list).

### `nextmail connected-mailboxes get`

Read one connected mailbox by id

```bash
nextmail connected-mailboxes get <id> [flags]
```

Looks up one connected mailbox and returns it in the same shape as a row of `list`: whether it is syncing, when it last finished, and what went wrong if it did not.

- Scopes: `threads:read`.
- Needs a sign-in.
- Aliases: `show`, `view`.

**Arguments**

- `<id>` (required): Connected mailbox id such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `list` returns it.

**Examples**

```bash
nextmail connected-mailboxes get cmb_5c1e9a7b3d2f48e6a0b4c7d1
```

Print the raw JSON

```bash
nextmail connected-mailboxes get cmb_5c1e9a7b3d2f48e6a0b4c7d1 --json
```

Also available in: API [`GET /connected-mailboxes/{id}`](https://nextmail.sh/docs/api/reference/connected-mailboxes#get-connected-mailboxes-id); TypeScript [`nextmail.connectedMailboxes.get()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#get); Python [`connected_mailboxes.get()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#get); Ruby [`connected_mailboxes.get`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#get); PHP [`connectedMailboxes->get`](https://nextmail.sh/docs/php/reference/connected-mailboxes#get); Go [`ConnectedMailboxes.Get`](https://nextmail.sh/docs/go/reference/connected-mailboxes#get); Java [`connectedMailboxes().get`](https://nextmail.sh/docs/java/reference/connected-mailboxes#get); C# [`ConnectedMailboxes.GetAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#get).

### `nextmail connected-mailboxes discover`

Find the mail servers for a mailbox

```bash
nextmail connected-mailboxes discover <email> [flags]
```

Looks up where the mailbox behind an address lives and what it signs in with, so the right password can be asked for before `connect`. Nothing is stored and no sign-in is attempted.

`signIn` is `app-password` for Gmail, Yahoo, iCloud and the other providers that want one, `password` where the everyday password works, and `microsoft` for Outlook.com and Microsoft 365, which only the Microsoft sign-in in the app can connect. `imap` is null when nothing was found: pass `host` to `connect`. `smtp` is null when the outgoing server is found while connecting, or can be passed as `smtpHost`.

- Scopes: `domains:write`.
- Needs a sign-in.

**Arguments**

- `<email>` (required): The address of the mailbox.

**Examples**

```bash
nextmail connected-mailboxes discover ada@gmail.com
```

Print the raw JSON

```bash
nextmail connected-mailboxes discover ada@gmail.com --json
```

Also available in: API [`GET /connected-mailboxes/settings`](https://nextmail.sh/docs/api/reference/connected-mailboxes#get-connected-mailboxes-settings); TypeScript [`nextmail.connectedMailboxes.discover()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#discover); Python [`connected_mailboxes.discover()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#discover); Ruby [`connected_mailboxes.discover`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#discover); PHP [`connectedMailboxes->discover`](https://nextmail.sh/docs/php/reference/connected-mailboxes#discover); Go [`ConnectedMailboxes.Discover`](https://nextmail.sh/docs/go/reference/connected-mailboxes#discover); Java [`connectedMailboxes().discover`](https://nextmail.sh/docs/java/reference/connected-mailboxes#discover); C# [`ConnectedMailboxes.DiscoverAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#discover).

### `nextmail connected-mailboxes connect`

Connect a mailbox at another provider

```bash
nextmail connected-mailboxes connect --email <value> --password <value> [flags]
nextmail connected-mailboxes connect --data <json|@file|-> [flags]
```

Connects a mailbox that stays at Gmail, Yahoo, iCloud or another provider, so its address becomes an address of the workspace while its mail stays where it is. It signs in to the incoming and the outgoing server with the password, keeps the password sealed, adds the address and starts copying new mail in within a minute.

From then on read, starred, archived, spam and deleted go back to the provider, and mail written as the address goes out through the provider, so it lands in its Sent folder too. With `importHistory: true` it also starts an import of the mail already in the mailbox, which `imports.get` follows by `historyImportId`.

Most providers want an app password, made in the account's security settings, not the everyday password. Leave `host` and `--smtp-host` out to have the servers found from the address, as `discover` shows.

- Scopes: `domains:write`.
- Needs a sign-in.

**Flags**

- `--email <value>`: The address of the mailbox, such as `you@gmail.com`. Required, here or in `--data`.
- `--password <value>`: The app password of the mailbox, or its password where the provider has no app passwords. Pass - to read it from standard input, or @path to read it from a file, so it stays out of your shell history. Required, here or in `--data`.
- `--host <value>`: The IMAP server. Left out, it is looked up from the address.
- `--port <n>`: The IMAP port: 993 with TLS, or 143 with STARTTLS.
- `--security <value>`: How the IMAP connection is encrypted: `tls` or `starttls`.
- `--username <value>`: The name to sign in with, when it is not the address.
- `--smtp-host <value>`: The SMTP server mail is sent through. Left out, it is found.
- `--smtp-port <n>`: The SMTP port: 465 with TLS, or 587 with STARTTLS.
- `--smtp-security <value>`: How the SMTP connection is encrypted: `tls` or `starttls`.
- `--label <value>`: A name for the address, shown beside it in the app, up to 120 characters.
- `--import-history`: Whether to copy the mail already in the mailbox as well. Left out, only mail that arrives from now on comes in.
- `--data <json|@file|->`: The whole `body` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

The required values only

```bash
nextmail connected-mailboxes connect --email ada@gmail.com --password @password.txt
```

With optional flags

```bash
nextmail connected-mailboxes connect --email ada@gmail.com --password @password.txt --label 'Ada (Gmail)' --import-history
```

Read the whole body from a JSON file

```bash
nextmail connected-mailboxes connect --data @connected-mailbox.json
```

Also available in: API [`POST /connected-mailboxes`](https://nextmail.sh/docs/api/reference/connected-mailboxes#post-connected-mailboxes); TypeScript [`nextmail.connectedMailboxes.connect()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#connect); Python [`connected_mailboxes.connect()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#connect); Ruby [`connected_mailboxes.connect`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#connect); PHP [`connectedMailboxes->connect`](https://nextmail.sh/docs/php/reference/connected-mailboxes#connect); Go [`ConnectedMailboxes.Connect`](https://nextmail.sh/docs/go/reference/connected-mailboxes#connect); Java [`connectedMailboxes().connect`](https://nextmail.sh/docs/java/reference/connected-mailboxes#connect); C# [`ConnectedMailboxes.ConnectAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#connect).

### `nextmail connected-mailboxes update`

Pause, resume or rename a connected mailbox, or give it a new password

```bash
nextmail connected-mailboxes update <id> [flags]
```

Changes a connected mailbox and resolves with it as it is now. Send only what changes: a field left out stays as it is.

`paused: true` stops syncing and sending through the mailbox, and `paused: false` starts both again. The mail already copied in stays either way. `password` gives it a new app password after the provider stopped accepting the old one: it is checked against both servers before it is kept, and a mailbox that needed signing in starts syncing again. `label` renames its address, and null clears the name.

- Scopes: `domains:write`.
- Needs a sign-in.
- Aliases: `edit`.

**Arguments**

- `<id>` (required): Connected mailbox id such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `list` returns it.

**Flags**

- `--paused`: `true` pauses the mailbox and `false` resumes it. Left out, it stays as it is.
- `--password <value>`: A new app password. Left out, the password stays. Pass - to read it from standard input, or @path to read it from a file, so it stays out of your shell history.
- `--label <value>`: A name for the address, up to 120 characters, or null to clear it. Left out, the name stays.
- `--data <json|@file|->`: The whole `patch` as JSON, inline, from a file with @path, or - for standard input. Flags override its keys.

**Examples**

```bash
nextmail connected-mailboxes update cmb_5c1e9a7b3d2f48e6a0b4c7d1
```

Print the raw JSON

```bash
nextmail connected-mailboxes update cmb_5c1e9a7b3d2f48e6a0b4c7d1 --json
```

Also available in: API [`PATCH /connected-mailboxes/{id}`](https://nextmail.sh/docs/api/reference/connected-mailboxes#patch-connected-mailboxes-id); TypeScript [`nextmail.connectedMailboxes.update()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#update); Python [`connected_mailboxes.update()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#update); Ruby [`connected_mailboxes.update`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#update); PHP [`connectedMailboxes->update`](https://nextmail.sh/docs/php/reference/connected-mailboxes#update); Go [`ConnectedMailboxes.Update`](https://nextmail.sh/docs/go/reference/connected-mailboxes#update); Java [`connectedMailboxes().update`](https://nextmail.sh/docs/java/reference/connected-mailboxes#update); C# [`ConnectedMailboxes.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#update).

### `nextmail connected-mailboxes sync`

Sync a connected mailbox now

```bash
nextmail connected-mailboxes sync <id> [flags]
```

Asks for a sync straight away instead of at the next interval, and resolves at once with the mailbox. The sync follows within seconds, and `lastSyncedAt` moves when it has finished.

A mailbox is synced every 30 seconds while mail comes in, and less often after it has been quiet for a while, down to every five minutes. A paused mailbox, or one that needs signing in, is not synced.

- Scopes: `threads:write`.
- Needs a sign-in.

**Arguments**

- `<id>` (required): Connected mailbox id such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `list` returns it.

**Examples**

```bash
nextmail connected-mailboxes sync cmb_5c1e9a7b3d2f48e6a0b4c7d1
```

Print the raw JSON

```bash
nextmail connected-mailboxes sync cmb_5c1e9a7b3d2f48e6a0b4c7d1 --json
```

Also available in: API [`POST /connected-mailboxes/{id}/sync`](https://nextmail.sh/docs/api/reference/connected-mailboxes#post-connected-mailboxes-id-sync); TypeScript [`nextmail.connectedMailboxes.sync()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#sync); Python [`connected_mailboxes.sync()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#sync); Ruby [`connected_mailboxes.sync`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#sync); PHP [`connectedMailboxes->sync`](https://nextmail.sh/docs/php/reference/connected-mailboxes#sync); Go [`ConnectedMailboxes.Sync`](https://nextmail.sh/docs/go/reference/connected-mailboxes#sync); Java [`connectedMailboxes().sync`](https://nextmail.sh/docs/java/reference/connected-mailboxes#sync); C# [`ConnectedMailboxes.SyncAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#sync).

### `nextmail connected-mailboxes disconnect`

Disconnect a mailbox

```bash
nextmail connected-mailboxes disconnect <id> [flags]
```

Stops syncing and sending through the mailbox, forgets its password and removes its address from the workspace. The mail already copied in stays in Nextmail, and nothing is changed at the provider. An import of its history that is still running is cancelled.

To stop it for a while and keep it, use `update` with `paused: true`. To use it again later, start over with `connect`.

- Scopes: `domains:write`.
- Needs a sign-in.
- Asks you to confirm.

**Arguments**

- `<id>` (required): Connected mailbox id such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `list` returns it.

**Examples**

```bash
nextmail connected-mailboxes disconnect cmb_5c1e9a7b3d2f48e6a0b4c7d1
```

Skip the confirmation, for scripts

```bash
nextmail connected-mailboxes disconnect cmb_5c1e9a7b3d2f48e6a0b4c7d1 --yes
```

Also available in: API [`DELETE /connected-mailboxes/{id}`](https://nextmail.sh/docs/api/reference/connected-mailboxes#delete-connected-mailboxes-id); TypeScript [`nextmail.connectedMailboxes.disconnect()`](https://nextmail.sh/docs/sdk/reference/connected-mailboxes#disconnect); Python [`connected_mailboxes.disconnect()`](https://nextmail.sh/docs/python/reference/connected-mailboxes#disconnect); Ruby [`connected_mailboxes.disconnect`](https://nextmail.sh/docs/ruby/reference/connected-mailboxes#disconnect); PHP [`connectedMailboxes->disconnect`](https://nextmail.sh/docs/php/reference/connected-mailboxes#disconnect); Go [`ConnectedMailboxes.Disconnect`](https://nextmail.sh/docs/go/reference/connected-mailboxes#disconnect); Java [`connectedMailboxes().disconnect`](https://nextmail.sh/docs/java/reference/connected-mailboxes#disconnect); C# [`ConnectedMailboxes.DisconnectAsync`](https://nextmail.sh/docs/csharp/reference/connected-mailboxes#disconnect).