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.
Returns
Every connected mailbox the caller may see.
Errors
The errors every operation can return400401403404422429500Error catalog
Also available in
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.
Request body
emailstringRequiredThe address of the mailbox, such as
you@gmail.com.3 to 320 characterspasswordstringRequiredThe 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.
1 to 1024 charactershoststringThe IMAP server. Leave it out to have it looked up from the address.
1 to 253 charactersportintegerThe IMAP port: 993 with TLS, or 143 with STARTTLS.
At least 1At most 65535securitystringHow the IMAP connection is encrypted.
One of"tls""starttls"usernamestringThe name to sign in with, when it is not the address.
1 to 320 characterssmtpHoststringThe SMTP server mail is sent through. Leave it out to have it found.
1 to 253 characterssmtpPortintegerThe SMTP port: 465 with TLS, or 587 with STARTTLS.
At least 1At most 65535smtpSecuritystringHow the SMTP connection is encrypted.
One of"tls""starttls"labelstringA name for the address, shown beside it in the app.
Can be nullUp to 120 charactersimportHistorybooleanWhether to copy the mail already in the mailbox as well. Without it only mail that arrives from now on comes in.
Returns
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 sendhost.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 sendsmtpHost.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 inRetry-After.- 502
mailbox_unreachable: the mail server did not answer.
The errors every operation can return401404500Error catalog
Also available in
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.
Query parameters
emailstringRequiredThe address of the mailbox.
Formatemail
Returns
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 inRetry-After.
The errors every operation can return401403404422500Error catalog
Also available in
- TypeScript
nextmail.connectedMailboxes.discover()- Python
connected_mailboxes.discover()- Ruby
connected_mailboxes.discover- PHP
connectedMailboxes->discover- Go
ConnectedMailboxes.Discover- Java
connectedMailboxes().discover- C#
ConnectedMailboxes.DiscoverAsync- CLI
nextmail connected-mailboxes discover- MCP
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.
Path parameters
idstringRequiredThe connected mailbox, such as
cmb_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connected-mailboxeslists it.
Returns
The mailbox.
Errors
- 404
connected_mailbox_not_found: no such connected mailbox in this workspace.
The errors every operation can return400401403422429500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe connected mailbox, such as
cmb_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connected-mailboxeslists it.
Request body
pausedbooleantruestops syncing and sending through the mailbox,falsestarts it again.passwordstringA new app password, after the old one stopped working. It is checked against both mail servers before it is kept.
1 to 1024 characterslabelstringA name for the address, or null to clear it.
Can be nullUp to 120 characters
Returns
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 sendhost.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 sendsmtpHost.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 inRetry-After.- 502
mailbox_unreachable: the mail server did not answer.
The errors every operation can return401422500Error catalog
Also available in
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.
Path parameters
idstringRequiredThe connected mailbox, such as
cmb_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connected-mailboxeslists it.
Returns
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 return400401422429500Error catalog
Also available in
- TypeScript
nextmail.connectedMailboxes.disconnect()- Python
connected_mailboxes.disconnect()- Ruby
connected_mailboxes.disconnect- PHP
connectedMailboxes->disconnect- Go
ConnectedMailboxes.Disconnect- Java
connectedMailboxes().disconnect- C#
ConnectedMailboxes.DisconnectAsync- CLI
nextmail connected-mailboxes disconnect- MCP
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.
Path parameters
idstringRequiredThe connected mailbox, such as
cmb_5c1e9a7b3d2f48e6a0b4c7d1, asGET /connected-mailboxeslists it.
Returns
The mailbox.
Errors
- 404
connected_mailbox_not_found: no such connected mailbox in this workspace.
The errors every operation can return400401403422429500Error catalog
Also available in
Objects
ConnectedMailboxobject
objectstringRequired- One of
"connected_mailbox" idstringRequiredThe id, which starts with
cmb_.addressIdstringRequiredThe address the mailbox appears as in the workspace, for the address and mail calls.
emailstringRequiredThe address of the mailbox, lower-cased.
FormatemaillabelstringRequiredThe name given to the address, if any.
Can be nullproviderstringRequiredThe provider the mailbox lives at, or
other.One of"gmail""outlook""yahoo""aol""icloud""fastmail""zoho""other"methodstringRequiredHow Nextmail reaches the mailbox:
imapwith an app password, ormicrosoftthrough a Microsoft sign-in made in the app.One of"imap""microsoft"statusstringRequiredactivesyncs and sends.pauseddoes neither until it is resumed.needs-sign-inmeans the provider stopped accepting the password: send a new one withPATCH, or sign in to Microsoft again in the app for amicrosoftmailbox.failingmeans the last five syncs failed, and it keeps trying less often.One of"active""paused""needs-sign-in""failing"pauseReasonstringRequiredWhy it is not
active:by-person,sign-inorunreachable. Null while active.Can be nullOne of"by-person""sign-in""unreachable"lastErrorstringRequiredWhat the mail server said the last time something went wrong, or null.
Can be nulllastSyncedAtstringRequiredWhen it last finished a sync, or null before the first one.
Can be nullFormatdate-timecreatedAtstringRequiredWhen it was connected.
Formatdate-timeconnectedBystringRequiredThe user id of the person who connected it.
usernamestringRequiredThe name it signs in with, usually the address.
Can be nullimapobjectRequiredThe server mail is read from, or null for a
microsoftmailbox.Can be nullhoststringRequiredThe host name, such as
imap.gmail.comorsmtp.gmail.com.portintegerRequiredThe port.
At least 1At most 65535securitystringRequiredtlsencrypts from the first byte,starttlsupgrades a plain connection.One of"tls""starttls"
smtpobjectRequiredThe server mail is sent through, or null for a
microsoftmailbox.Can be nullhoststringRequiredThe host name, such as
imap.gmail.comorsmtp.gmail.com.portintegerRequiredThe port.
At least 1At most 65535securitystringRequiredtlsencrypts from the first byte,starttlsupgrades a plain connection.One of"tls""starttls"
historyImportIdstringRequiredThe import that copies the mail already in the mailbox, when
importHistorywas asked for, as the imports calls name it.Can be null
ConnectedMailboxListobject
objectstring- One of
"list"
ConnectedMailboxSettingsobject
objectstringRequired- One of
"connected_mailbox_settings" emailstringRequiredThe address looked up, lower-cased.
FormatemailproviderstringRequiredThe provider the address belongs to, or
other.One of"gmail""outlook""yahoo""aol""icloud""fastmail""zoho""other"signInstringRequiredapp-passwordandpasswordare whatPOST /connected-mailboxestakes.microsoftmeans the mailbox only opens through the Microsoft sign-in in the app.One of"app-password""password""microsoft"imapobjectRequiredWhere mail is read from, or null when nothing was found and
hosthas to be given.Can be nullhoststringRequiredThe host name, such as
imap.gmail.comorsmtp.gmail.com.portintegerRequiredThe port.
At least 1At most 65535securitystringRequiredtlsencrypts from the first byte,starttlsupgrades a plain connection.One of"tls""starttls"
smtpobjectRequiredWhere mail is sent through, when the provider is known. Null means it is found when the mailbox is connected, or
smtpHostcan be given.Can be nullhoststringRequiredThe host name, such as
imap.gmail.comorsmtp.gmail.com.portintegerRequiredThe port.
At least 1At most 65535securitystringRequiredtlsencrypts from the first byte,starttlsupgrades a plain connection.One of"tls""starttls"
DeletedConnectedMailboxobject
objectstringRequired- One of
"connected_mailbox" idstringRequiredThe id of the mailbox that was disconnected.
addressIdstringRequiredThe address it appeared as.
emailstringRequiredThe address of the mailbox.
FormatemaildeletedbooleanRequired- One of
true
Google Workspace
Fastmail