Java

client.connectedMailboxes()

Every method in this namespace: its signature, its parameters, what it returns and an example.

Methods

Mailboxes that stay at Gmail, Yahoo, iCloud or another provider and are worked from Nextmail: find their mail servers, connect one with an app password, see whether it syncs, pause, resume or rename it, give it a new password, sync it now and disconnect it. 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.

`connectedMailboxes().list`

List the connected mailboxes

threads:read

Signature

List<Map<String, Object>> list(RequestOptions options)

Returns every mailbox connected to the workspace in one list, 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.

Parameters

options.apiKeyString: Overrides the client's API key for this call only.

Returns

A list of connected mailbox maps. Each item has id, addressId, email, label, provider, method, status, pauseReason, lastError, lastSyncedAt, createdAt, connectedBy, username, imap, smtp and historyImportId.

Example

List<Map<String, Object>> mailboxes = client.connectedMailboxes().list(); for (Map<String, Object> mailbox : mailboxes) {    System.out.println(mailbox.get("email") + " " + mailbox.get("status") + " " + mailbox.get("lastSyncedAt"));}

Notes

A key or an app limited to particular addresses sees only the mailboxes of those addresses.
lastError is what the mail server said the last time something went wrong, and null while nothing is wrong. pauseReason says why a mailbox is not active, as by-person, sign-in or unreachable, and is null while it is.
imap and smtp are maps with host, port and security: the server mail is read from and the server it is sent through.
The values of status are in sh.nextmail.constants.ConnectedMailboxStatuses, those of method in sh.nextmail.constants.ConnectedMailboxMethods and those of pauseReason in sh.nextmail.constants.ConnectedMailboxPauseReasons.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connected-mailboxes
TypeScript: nextmail.connectedMailboxes.list()
Python: connected_mailboxes.list()
Ruby: connected_mailboxes.list
PHP: connectedMailboxes->list
Go: ConnectedMailboxes.List
C#: ConnectedMailboxes.ListAsync
CLI: openemail connected-mailboxes list

`connectedMailboxes().get`

Read one connected mailbox by id

threads:read

Signature

Map<String, Object> get(String id, RequestOptions options)

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.

Parameters

idStringRequired: Connected mailbox id such as cmb_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map with id, addressId, email, label, provider, method, status, pauseReason, lastError, lastSyncedAt, createdAt, connectedBy, username, imap, smtp and historyImportId.

Example

Map<String, Object> mailbox = client.connectedMailboxes().get("cmb_5c1e9a7b3d2f48e6a0b4c7d1"); if ("needs-sign-in".equals(mailbox.get("status"))) {    System.out.println("Send a new app password with update");}

Notes

A missing mailbox, or one whose address the caller cannot reach, throws a NotFoundException, whose isNotFound() is true and whose code() is connected_mailbox_not_found.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connected-mailboxes/{id}
TypeScript: nextmail.connectedMailboxes.get()
Python: connected_mailboxes.get()
Ruby: connected_mailboxes.get
PHP: connectedMailboxes->get
Go: ConnectedMailboxes.Get
C#: ConnectedMailboxes.GetAsync
CLI: openemail connected-mailboxes get

`connectedMailboxes().discover`

Find the mail servers for a mailbox

domains:write

Signature

Map<String, Object> discover(String email, RequestOptions options)

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.

Parameters

emailStringRequired: The address of the mailbox.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map with email, provider, signIn, imap and smtp. imap and smtp are maps with host, port and security, or null.

Example

Map<String, Object> settings = client.connectedMailboxes().discover("[email protected]"); if ("app-password".equals(settings.get("signIn"))) {    System.out.println("Make an app password at " + settings.get("provider"));}

Notes

Something that is not an email address is a 400 mailbox_address_invalid.
Too many lookups in an hour is a 429 mailbox_checks_limited.
A GET is retried automatically on network failure and on 408, 500, 502, 503 and 504 responses, up to the client maxRetries, and on a 429 only when it carries a Retry-After of a minute or less.

Also available in

API: GET /connected-mailboxes/settings
TypeScript: nextmail.connectedMailboxes.discover()
Python: connected_mailboxes.discover()
Ruby: connected_mailboxes.discover
PHP: connectedMailboxes->discover
Go: ConnectedMailboxes.Discover
C#: ConnectedMailboxes.DiscoverAsync
CLI: openemail connected-mailboxes discover

`connectedMailboxes().connect`

Connect a mailbox at another provider

domains:write

Signature

Map<String, Object> connect(Map<String, Object> body, RequestOptions options)

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 Body.of("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. Read it from an environment variable or your secrets store rather than writing it in code. Leave host and smtpHost out to have the servers found from the address, as discover shows.

Parameters

body.emailStringRequired: The address of the mailbox, such as [email protected].
body.passwordStringRequired: The app password of the mailbox, or its password where the provider has no app passwords.
body.hostString: The IMAP server. Left out, it is looked up from the address.
body.portint: The IMAP port: 993 with TLS, or 143 with STARTTLS.
body.securityString: How the IMAP connection is encrypted: tls or starttls.
body.usernameString: The name to sign in with, when it is not the address.
body.smtpHostString: The SMTP server mail is sent through. Left out, it is found.
body.smtpPortint: The SMTP port: 465 with TLS, or 587 with STARTTLS.
body.smtpSecurityString: How the SMTP connection is encrypted: tls or starttls.
body.labelString or null: A name for the address, shown beside it in the app, up to 120 characters.
body.importHistoryboolean: Whether to copy the mail already in the mailbox as well. Left out, only mail that arrives from now on comes in.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map, the connected mailbox with a new id, the addressId it appears as in the workspace, and status set to active.

Example

Map<String, Object> mailbox = client.connectedMailboxes().connect(Body.of(    "email", "[email protected]",    "password", System.getenv("GMAIL_APP_PASSWORD"),    "label", "Ada (Gmail)",    "importHistory", true)); System.out.println(mailbox.get("id") + " " + mailbox.get("addressId") + " " + mailbox.get("status"));

Notes

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 emails().send with an API key refuse it as the sender.
A wrong password is a 400 mailbox_login_failed, and an outgoing server that refuses it a 400 connected_mailbox_send_sign_in_failed. No server found is a 400 mailbox_settings_unknown or connected_mailbox_send_server_unknown. An Outlook.com or Microsoft 365 mailbox is a 400 mailbox_uses_microsoft: connect it with the Microsoft sign-in in the app, and manage it from here after that.
An address whose mail already comes to Nextmail is a 400 connected_mailbox_domain_hosted. A mailbox already connected here is a 409 connected_mailbox_already_connected, and one connected to another workspace a 409 connected_mailbox_connected_elsewhere.
The address counts toward the addresses of the plan, and a full plan is a 422 workspace_limit_reached. A key or an app limited to particular addresses or domains is refused with 422 capability_unsupported.
Each person may make 10 sign-in attempts an hour across this call, update with a password and the mailbox calls of imports(), and more is a 429 mailbox_checks_limited.
Not retried automatically: a retry after a lost response answers 409 connected_mailbox_already_connected, which then means the first call went through.

Also available in

API: POST /connected-mailboxes
TypeScript: nextmail.connectedMailboxes.connect()
Python: connected_mailboxes.connect()
Ruby: connected_mailboxes.connect
PHP: connectedMailboxes->connect
Go: ConnectedMailboxes.Connect
C#: ConnectedMailboxes.ConnectAsync
CLI: openemail connected-mailboxes connect

`connectedMailboxes().update`

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

domains:write

Signature

Map<String, Object> update(String id, Map<String, Object> patch, RequestOptions options)

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

Body.of("paused", true) stops syncing and sending through the mailbox, and Body.of("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 Body.of("label", null) clears the name.

Parameters

idStringRequired: Connected mailbox id such as cmb_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
patch.pausedboolean: True pauses the mailbox and false resumes it. Left out, it stays as it is.
patch.passwordString: A new app password. Left out, the password stays.
patch.labelString or null: A name for the address, up to 120 characters, or null to clear it. Left out, the name stays.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map, the connected mailbox with its unchanged id, and status, pauseReason and label as they are now.

Example

Map<String, Object> mailbox = client.connectedMailboxes().update("cmb_5c1e9a7b3d2f48e6a0b4c7d1", Body.of("password", System.getenv("GMAIL_APP_PASSWORD"))); System.out.println(mailbox.get("status"));

Notes

A mailbox that needs signing in cannot be paused or resumed until it has a new password, or until a microsoft one is signed in again in the app.
A password the mail server refuses is a 400 mailbox_login_failed or connected_mailbox_send_sign_in_failed, and the old one stays. A microsoft mailbox has no password to change, which is a 400 connected_mailbox_no_password: it signs in again in the app. A missing mailbox is a 404 connected_mailbox_not_found.
A value of the wrong type or length is 422 invalid_parameter, and a key the patch does not take 422 unknown_parameter.
Not retried automatically. Read it with get before you try again.

Also available in

API: PATCH /connected-mailboxes/{id}
TypeScript: nextmail.connectedMailboxes.update()
Python: connected_mailboxes.update()
Ruby: connected_mailboxes.update
PHP: connectedMailboxes->update
Go: ConnectedMailboxes.Update
C#: ConnectedMailboxes.UpdateAsync
CLI: openemail connected-mailboxes update

`connectedMailboxes().sync`

Sync a connected mailbox now

threads:write

Signature

Map<String, Object> sync(String id, RequestOptions options)

Asks for a sync straight away instead of at the next interval, and returns 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. It takes no body.

Parameters

idStringRequired: Connected mailbox id such as cmb_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map, the connected mailbox as it was when the sync was asked for.

Example

Map<String, Object> mailbox = client.connectedMailboxes().sync("cmb_5c1e9a7b3d2f48e6a0b4c7d1"); System.out.println(mailbox.get("email") + " " + mailbox.get("status"));

Notes

A missing mailbox is a 404 connected_mailbox_not_found.
Asking twice does no harm, so the SDK retries this call after a network failure.

Also available in

API: POST /connected-mailboxes/{id}/sync
TypeScript: nextmail.connectedMailboxes.sync()
Python: connected_mailboxes.sync()
Ruby: connected_mailboxes.sync
PHP: connectedMailboxes->sync
Go: ConnectedMailboxes.Sync
C#: ConnectedMailboxes.SyncAsync
CLI: openemail connected-mailboxes sync

`connectedMailboxes().disconnect`

Disconnect a mailbox

domains:write

Signature

Map<String, Object> disconnect(String id, RequestOptions options)

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 Body.of("paused", true). To use it again later, start over with connect.

Parameters

idStringRequired: Connected mailbox id such as cmb_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
options.apiKeyString: Overrides the client's API key for this call only.

Returns

A map with object set to connected_mailbox, the id, the addressId the mailbox appeared as, its email, and deleted set to true.

Example

Map<String, Object> removed = client.connectedMailboxes().disconnect("cmb_5c1e9a7b3d2f48e6a0b4c7d1"); System.out.println(removed.get("email") + " " + removed.get("deleted"));

Notes

A missing mailbox is a 404 connected_mailbox_not_found.
The SDK retries this call after a network failure. When the first attempt went through and only its answer was lost, the retry answers 404 connected_mailbox_not_found, which then means the mailbox is disconnected.

Also available in

API: DELETE /connected-mailboxes/{id}
TypeScript: nextmail.connectedMailboxes.disconnect()
Python: connected_mailboxes.disconnect()
Ruby: connected_mailboxes.disconnect
PHP: connectedMailboxes->disconnect
Go: ConnectedMailboxes.Disconnect
C#: ConnectedMailboxes.DisconnectAsync
CLI: openemail connected-mailboxes disconnect

client.connectedMailboxes()

Methods

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Parameters

Returns

Example

Notes

Also available in

Your inbox,on your own terms.

Your inbox,
on your own terms.