---
title: "How connectors work"
description: "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."
url: "https://openemail.uk/docs/api/connectors/overview"
area: "API"
category: "Mailbox"
---

# 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

1. `POST /connectors` with the `app` starts a connection. It returns the connector, still `pending`, with a `connectUrl`.
2. 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.
3. 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.