--- title: "Connected mailboxes" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://nextmail.sh/docs/api/reference/connected-mailboxes" area: "API" category: "Reference" --- # Connected mailboxes Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations Mailboxes that stay at Gmail, Outlook, Yahoo, iCloud or another provider and are worked from Nextmail. New mail is copied in within minutes, read, starred, archived, spam and deleted go back to the provider, and mail written as the address is sent through the provider, so it lands in its Sent folder as well. An Outlook.com or Microsoft 365 mailbox is connected in the app with a Microsoft sign-in, and then works here like any other. ### `GET /connected-mailboxes` List connected mailboxes Lists the mailboxes connected to this workspace, newest first. A key or app limited to particular addresses sees only the mailboxes of those addresses. Requires the `threads:read` scope. - Scopes: `threads:read`. **Returns** - `200` `ConnectedMailboxList`: Every connected mailbox the caller may see. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes list`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-list); MCP [`listConnectedMailboxes`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#listConnectedMailboxes). ### `POST /connected-mailboxes` Connect a mailbox Connects a mailbox at 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. With `importHistory` it also starts an import of the mail already there, which `GET /imports/{id}` follows. Gmail, Yahoo, iCloud and most providers need an app password, made in the account's security settings, not the everyday password. Leave `host` and `smtpHost` out to have the servers found from the address, as `GET /connected-mailboxes/settings` shows. Mail from a connected address is sent through the provider, never through Nextmail's servers, and only to people: broadcasts, automations, sign-up forms and API sends from it are refused. A key or app limited to particular addresses or domains cannot connect a mailbox. The address counts toward the plan's addresses, and every sign-in attempt counts toward the 10 an hour each person may make. Requires the `domains:write` scope. - Scopes: `domains:write`. **Request body** - `email` (`string`, required, 3 to 320 characters): The address of the mailbox, such as `you@gmail.com`. - `password` (`string`, required, 1 to 1024 characters): The app password of the mailbox, or its password where the provider has no app passwords. It is kept sealed and used only to sign in to its mail servers. - `host` (`string`, 1 to 253 characters): The IMAP server. Leave it out to have it looked up from the address. - `port` (`integer`, at least 1, at most 65535): The IMAP port: 993 with TLS, or 143 with STARTTLS. - `security` (`string`, one of `"tls"`, `"starttls"`): How the IMAP connection is encrypted. - `username` (`string`, 1 to 320 characters): The name to sign in with, when it is not the address. - `smtpHost` (`string`, 1 to 253 characters): The SMTP server mail is sent through. Leave it out to have it found. - `smtpPort` (`integer`, at least 1, at most 65535): The SMTP port: 465 with TLS, or 587 with STARTTLS. - `smtpSecurity` (`string`, one of `"tls"`, `"starttls"`): How the SMTP connection is encrypted. - `label` (`string`, nullable, up to 120 characters): A name for the address, shown beside it in the app. - `importHistory` (`boolean`): Whether to copy the mail already in the mailbox as well. Without it only mail that arrives from now on comes in. **Returns** - `201` `ConnectedMailbox`: The mailbox, with `status` `active`. **Errors** - `400`: `mailbox_login_failed`: the mail server did not accept the address and password. `mailbox_settings_unknown`: no server was found for the address, so send `host`. `mailbox_host_not_allowed`: the host is not public, or the port is not 993 or 143. `mailbox_uses_microsoft`: the mailbox only opens through the Microsoft sign-in in the app. `connected_mailbox_send_sign_in_failed`: the outgoing server refused the password. `connected_mailbox_send_server_unknown`: no outgoing server answered, so send `smtpHost`. `connected_mailbox_domain_hosted`: mail for the address already comes to Nextmail, so it needs no connecting. - `403`: `connected_mailbox_not_allowed`: the caller may not connect mailboxes, or the key lacks the scope. - `409`: `connected_mailbox_already_connected`: the mailbox is already connected here. `connected_mailbox_connected_elsewhere`: another workspace has it connected. - `422`: `workspace_limit_reached`: the plan holds no more addresses. `capability_unsupported`: the key or app is limited to particular addresses or domains. - `429`: `mailbox_checks_limited`: too many sign-in attempts in the last hour. `rate_limited`: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in `Retry-After`. - `502`: `mailbox_unreachable`: the mail server did not answer. - The errors every operation can return: `401`, `404`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes connect`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-connect). ### `GET /connected-mailboxes/settings` Find the mail servers for a mailbox Looks up where the mailbox behind an address lives and what it signs in with, so the right password can be asked for before connecting it. Nothing is stored and no sign-in is attempted. Requires the `domains:write` scope. - Scopes: `domains:write`. **Query parameters** - `email` (`string`, required, format `email`): The address of the mailbox. **Returns** - `200` `ConnectedMailboxSettings`: What was found for the address. **Errors** - `400`: `mailbox_address_invalid`: that is not an email address. - `429`: `mailbox_checks_limited`: too many lookups in the last hour. `rate_limited`: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in `Retry-After`. - The errors every operation can return: `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes discover`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-discover); MCP [`getConnectedMailboxSettings`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#getConnectedMailboxSettings). ### `GET /connected-mailboxes/{id}` Get a connected mailbox Returns one connected mailbox: whether it is syncing, when it last did, and what went wrong if it did not. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The connected mailbox, such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connected-mailboxes` lists it. **Returns** - `200` `ConnectedMailbox`: The mailbox. **Errors** - `404`: `connected_mailbox_not_found`: no such connected mailbox in this workspace. - The errors every operation can return: `400`, `401`, `403`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes get`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-get); MCP [`getConnectedMailbox`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#getConnectedMailbox). ### `PATCH /connected-mailboxes/{id}` Update a connected mailbox Pauses or resumes it, renames its address, or gives it a new app password after the provider stopped accepting the old one. A new password is checked against both servers before it is kept, and a mailbox that needed signing in starts syncing again. Pausing stops both syncing and sending through it; mail already copied in stays. Requires the `domains:write` scope. - Scopes: `domains:write`. **Path parameters** - `id` (`string`, required): The connected mailbox, such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connected-mailboxes` lists it. **Request body** - `paused` (`boolean`): `true` stops syncing and sending through the mailbox, `false` starts it again. - `password` (`string`, 1 to 1024 characters): A new app password, after the old one stopped working. It is checked against both mail servers before it is kept. - `label` (`string`, nullable, up to 120 characters): A name for the address, or null to clear it. **Returns** - `200` `ConnectedMailbox`: The mailbox as it is now. **Errors** - `400`: `mailbox_login_failed`: the mail server did not accept the address and password. `mailbox_settings_unknown`: no server was found for the address, so send `host`. `mailbox_host_not_allowed`: the host is not public, or the port is not 993 or 143. `mailbox_uses_microsoft`: the mailbox only opens through the Microsoft sign-in in the app. `connected_mailbox_send_sign_in_failed`: the outgoing server refused the password. `connected_mailbox_send_server_unknown`: no outgoing server answered, so send `smtpHost`. `connected_mailbox_no_password`: the mailbox signs in with Microsoft, so it has no password to change. - `403`: `connected_mailbox_not_allowed`: the caller may not change connected mailboxes. - `404`: `connected_mailbox_not_found`: no such connected mailbox in this workspace. - `429`: `mailbox_checks_limited`: too many sign-in attempts in the last hour. `rate_limited`: the key or app made more than 600 requests in 60 seconds. Wait for the seconds in `Retry-After`. - `502`: `mailbox_unreachable`: the mail server did not answer. - The errors every operation can return: `401`, `422`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes update`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-update); MCP [`updateConnectedMailbox`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#updateConnectedMailbox). ### `DELETE /connected-mailboxes/{id}` Disconnect a mailbox 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. Requires the `domains:write` scope. - Scopes: `domains:write`. **Path parameters** - `id` (`string`, required): The connected mailbox, such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connected-mailboxes` lists it. **Returns** - `200` `DeletedConnectedMailbox`: The mailbox that was disconnected. **Errors** - `403`: `connected_mailbox_not_allowed`: the caller may not change connected mailboxes. - `404`: `connected_mailbox_not_found`: no such connected mailbox in this workspace. - The errors every operation can return: `400`, `401`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes disconnect`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-disconnect); MCP [`disconnectConnectedMailbox`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#disconnectConnectedMailbox). ### `POST /connected-mailboxes/{id}/sync` Sync a connected mailbox now Asks for a sync straight away instead of at the next interval. A mailbox is synced every 30 seconds while mail comes in, and less often after it has been quiet for a while. It answers at once; the sync follows within seconds. A paused mailbox, or one that needs signing in, is not synced. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The connected mailbox, such as `cmb_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connected-mailboxes` lists it. **Returns** - `200` `ConnectedMailbox`: The mailbox. **Errors** - `404`: `connected_mailbox_not_found`: no such connected mailbox in this workspace. - The errors every operation can return: `400`, `401`, `403`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: 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); CLI [`nextmail connected-mailboxes sync`](https://nextmail.sh/docs/cli/reference/connected-mailboxes#connected-mailboxes-sync); MCP [`syncConnectedMailbox`](https://nextmail.sh/docs/mcp/tools/connected-mailboxes#syncConnectedMailbox). ### Objects #### `ConnectedMailbox` `object` - `object` (`string`, required, one of `"connected_mailbox"`) - `id` (`string`, required): The id, which starts with `cmb_`. - `addressId` (`string`, required): The address the mailbox appears as in the workspace, for the address and mail calls. - `email` (`string`, required, format `email`): The address of the mailbox, lower-cased. - `label` (`string`, required, nullable): The name given to the address, if any. - `provider` (`string`, required, one of `"gmail"`, `"outlook"`, `"yahoo"`, `"aol"`, `"icloud"`, `"fastmail"`, `"zoho"`, `"other"`): The provider the mailbox lives at, or `other`. - `method` (`string`, required, one of `"imap"`, `"microsoft"`): How Nextmail reaches the mailbox: `imap` with an app password, or `microsoft` through a Microsoft sign-in made in the app. - `status` (`string`, required, one of `"active"`, `"paused"`, `"needs-sign-in"`, `"failing"`): `active` syncs and sends. `paused` does neither until it is resumed. `needs-sign-in` means the provider stopped accepting the password: send a new one with `PATCH`, or sign in to Microsoft again in the app for a `microsoft` mailbox. `failing` means the last five syncs failed, and it keeps trying less often. - `pauseReason` (`string`, required, nullable, one of `"by-person"`, `"sign-in"`, `"unreachable"`): Why it is not `active`: `by-person`, `sign-in` or `unreachable`. Null while active. - `lastError` (`string`, required, nullable): What the mail server said the last time something went wrong, or null. - `lastSyncedAt` (`string`, required, nullable, format `date-time`): When it last finished a sync, or null before the first one. - `createdAt` (`string`, required, format `date-time`): When it was connected. - `connectedBy` (`string`, required): The user id of the person who connected it. - `username` (`string`, required, nullable): The name it signs in with, usually the address. - `imap` (`object`, required, nullable): The server mail is read from, or null for a `microsoft` mailbox. - `host` (`string`, required): The host name, such as `imap.gmail.com` or `smtp.gmail.com`. - `port` (`integer`, required, at least 1, at most 65535): The port. - `security` (`string`, required, one of `"tls"`, `"starttls"`): `tls` encrypts from the first byte, `starttls` upgrades a plain connection. - `smtp` (`object`, required, nullable): The server mail is sent through, or null for a `microsoft` mailbox. - `host` (`string`, required): The host name, such as `imap.gmail.com` or `smtp.gmail.com`. - `port` (`integer`, required, at least 1, at most 65535): The port. - `security` (`string`, required, one of `"tls"`, `"starttls"`): `tls` encrypts from the first byte, `starttls` upgrades a plain connection. - `historyImportId` (`string`, required, nullable): The import that copies the mail already in the mailbox, when `importHistory` was asked for, as the imports calls name it. #### `ConnectedMailboxList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectedMailbox[]`) #### `ConnectedMailboxSettings` `object` - `object` (`string`, required, one of `"connected_mailbox_settings"`) - `email` (`string`, required, format `email`): The address looked up, lower-cased. - `provider` (`string`, required, one of `"gmail"`, `"outlook"`, `"yahoo"`, `"aol"`, `"icloud"`, `"fastmail"`, `"zoho"`, `"other"`): The provider the address belongs to, or `other`. - `signIn` (`string`, required, one of `"app-password"`, `"password"`, `"microsoft"`): `app-password` and `password` are what `POST /connected-mailboxes` takes. `microsoft` means the mailbox only opens through the Microsoft sign-in in the app. - `imap` (`object`, required, nullable): Where mail is read from, or null when nothing was found and `host` has to be given. - `host` (`string`, required): The host name, such as `imap.gmail.com` or `smtp.gmail.com`. - `port` (`integer`, required, at least 1, at most 65535): The port. - `security` (`string`, required, one of `"tls"`, `"starttls"`): `tls` encrypts from the first byte, `starttls` upgrades a plain connection. - `smtp` (`object`, required, nullable): Where mail is sent through, when the provider is known. Null means it is found when the mailbox is connected, or `smtpHost` can be given. - `host` (`string`, required): The host name, such as `imap.gmail.com` or `smtp.gmail.com`. - `port` (`integer`, required, at least 1, at most 65535): The port. - `security` (`string`, required, one of `"tls"`, `"starttls"`): `tls` encrypts from the first byte, `starttls` upgrades a plain connection. #### `DeletedConnectedMailbox` `object` - `object` (`string`, required, one of `"connected_mailbox"`) - `id` (`string`, required): The id of the mailbox that was disconnected. - `addressId` (`string`, required): The address it appeared as. - `email` (`string`, required, format `email`): The address of the mailbox. - `deleted` (`boolean`, required, one of `true`)