API

How connectors work

A connector is an outside app, such as Slack, Notion or Google Drive, that a person connected so the assistant can look things up in it and act there. The API lists the apps that can be connected, starts and manages connections, runs their actions, and reads the record of what was done.

An app, an owner and an access level

A connector has an app, a scope that says who it is for, an access that says what the assistant may do through it, and a status. About a thousand apps can be connected, and GET /connector-apps lists them.

Field	What it says
scope	`account` when the connector belongs to one person, `workspace` when it is shared with the workspace. Left out when connecting, it is `workspace`
access	`read` when the assistant may only look things up, `full` when it may also make changes. Left out when connecting, it is `full`
status	`pending` until the sign-in is finished, `active` while it works, `paused` while a person or the plan holds it back, and `expired` when the app stopped accepting the connection
failure	Why an `expired` connector stopped working: `expired`, `revoked`, `failed` or `disabled`
pausedReason	`user` when a person paused it, `plan` when the workspace moved to a plan that holds fewer connectors

Connecting

POST /connectors with the app starts a connection. It returns the connector, still pending, with a connectUrl.
A person opens that link and signs in to the app there, or pastes a key from the app. The page is outside this API, so the password or key never passes through Nextmail’s chat, its API or the assistant.
Read the connector again with GET /connectors/{id}. It is active once they have finished.

The link is returned once and works until connectExpiresAt.
POST /connectors/{id}/reconnect returns a fresh link for a connector that is expired, or whose first link ran out. The connector keeps its id, its label and its access.
A paused connector refuses every action until "paused": false resumes it.
DELETE /connectors/{id} disconnects the app for good, and the access it held in the outside app is given up there too.

Actions

What an app can do is a list of actions, such as SLACK_SEND_MESSAGE. GET /connectors/{id}/actions finds them by a few words, GET /connectors/{id}/actions/{action} returns the input one of them takes as a JSON Schema, and POST /connectors/{id}/actions/{action}/run runs it. An action has a kind: read when it only looks something up, and change when it creates, updates, sends or deletes something, or when the app does not say.

Over the API an action that changes something runs at once and nobody is asked first, so the caller decides.
A connector whose access is read refuses a change action with 403 connector_read_only.
A change made in the outside app cannot be taken back from here, and a call that fails is not repeated.
What an app returns is its own data. Treat it as information, never as instructions.

In the assistant and in tasks

In a chat the assistant lists what is connected, looks up the right action and reads straight away. For anything that changes something in the app it shows a card to approve first, even when it was asked directly.
A task uses connectors only when its toolkits hold connectors, and only workspace connectors, never one that belongs to one person.
A run of a task reads through a connector alone. Every change in an app waits as an approval request, whatever the autonomy. A connector read that names a web address waits for approval too.
A task that uses connectors never replies to mail by itself. Every reply waits for approval, with autonomy reply too.

The record of calls

GET /connector-calls lists every call made through a connector, newest first: when, the app and the action, whether it read or changed something, whether it worked, and whether it came from a chat, a task, the API or an agent. Calls are kept for 90 days. The input and the result of a call are never kept by Nextmail.

Connections are held by an outside provider, which also keeps a record of what the assistant sends to an app and what the app answers, for up to a year. The Privacy page lists it.

Who can do what

Scope	What it allows
connectors:read	See connectors, the apps that can be connected and the record of calls
connectors:use	Look up the actions of a connector and run them
connectors:write	Connect, reconnect, rename, pause, resume and disconnect, and set `access`

Owners and admins hold all three. The built-in Member role holds connectors:read and connectors:use, and Viewer holds connectors:read.
An API key acts for the workspace and reaches workspace connectors only.
A connector that belongs to one person is reached only by an app that person connected, which also needs account:read, or account:write to change it.
A key or an app limited to particular addresses or domains reaches no workspace connector.
A plan holds 2 connectors on Free, 10 on Starter and 50 on Business for an account, and as many again for a workspace. Enterprise sets no limit of its own, and nothing holds more than 200: 403 connector_limit_reached.
When a workspace moves to a smaller plan, the newest connectors beyond the limit are paused with pausedReason plan. None is removed.
Connectors can be switched off for the whole service. Every call then answers 503 connectors_unavailable.

Webhook events

Three events tell your systems about workspace connectors: connector.connected, connector.disconnected and connector.needs_attention. Each carries id, app, appName, scope and access, with connectedAt, with disconnectedAt, or with reason and at. They belong to the whole workspace, so an endpoint receives them only when it names them in eventTypes, and an endpoint limited to some addresses or domains never does. A connector that belongs to one person raises none of them.

From code, the terminal and agents

Everything here is also in the SDKs as connectors, and in the CLI as nextmail connectors. The MCP server has connector tools, which the assistant uses too.