--- title: "Connectors" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://openemail.uk/docs/api/reference/connectors" area: "API" category: "Reference" --- # Connectors Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations Outside apps, such as Slack, Notion or Google Drive, that a person connects so the assistant can look things up in them and act there. A connector belongs to one person (`account`) or to the workspace (`workspace`). ### `GET /connector-apps` List apps that can be connected The catalogue of apps that can be connected, most used first, as the Browse tab of the Connectors page shows it. Narrow it with `search` or `category`. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Query parameters** - `search` (`string`): Words to look for in the name or the description. - `category` (`string`): A category slug from the catalogue, to list only the apps in it. - `limit` (`integer`, at least 1, at most 60, default `24`): Rows per page, 1 to 60. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `ConnectorAppList`: A page of apps. **Errors** - `503`: `connectors_unavailable`: connectors are not switched on. `connector_provider_failed`: the connection service did not answer. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.listApps()`](https://openemail.uk/docs/sdk/reference/connectors#listApps), [`connectors.listAllApps()`](https://openemail.uk/docs/sdk/reference/connectors#listAllApps), [`connectors.iterateApps()`](https://openemail.uk/docs/sdk/reference/connectors#iterateApps); Python [`connectors.list_apps()`](https://openemail.uk/docs/python/reference/connectors#listApps), [`connectors.list_all_apps()`](https://openemail.uk/docs/python/reference/connectors#listAllApps), [`connectors.iterate_apps()`](https://openemail.uk/docs/python/reference/connectors#iterateApps); Ruby [`connectors.list_apps`](https://openemail.uk/docs/ruby/reference/connectors#listApps), [`connectors.list_all_apps`](https://openemail.uk/docs/ruby/reference/connectors#listAllApps), [`connectors.iterate_apps`](https://openemail.uk/docs/ruby/reference/connectors#iterateApps); PHP [`connectors->listApps`](https://openemail.uk/docs/php/reference/connectors#listApps), [`connectors->listAllApps`](https://openemail.uk/docs/php/reference/connectors#listAllApps), [`connectors->iterateApps`](https://openemail.uk/docs/php/reference/connectors#iterateApps); Go [`Connectors.ListApps`](https://openemail.uk/docs/go/reference/connectors#listApps), [`Connectors.ListAllApps`](https://openemail.uk/docs/go/reference/connectors#listAllApps), [`Connectors.IterateApps`](https://openemail.uk/docs/go/reference/connectors#iterateApps); Java [`connectors().listApps`](https://openemail.uk/docs/java/reference/connectors#listApps), [`connectors().listAllApps`](https://openemail.uk/docs/java/reference/connectors#listAllApps), [`connectors().iterateApps`](https://openemail.uk/docs/java/reference/connectors#iterateApps); C# [`Connectors.ListAppsAsync`](https://openemail.uk/docs/csharp/reference/connectors#listApps), [`Connectors.ListAllAppsAsync`](https://openemail.uk/docs/csharp/reference/connectors#listAllApps), [`Connectors.IterateAppsAsync`](https://openemail.uk/docs/csharp/reference/connectors#iterateApps); CLI [`openemail connectors list-apps`](https://openemail.uk/docs/cli/reference/connectors#connectors-list-apps); MCP [`listConnectorApps`](https://openemail.uk/docs/mcp/tools/connectors#listConnectorApps). ### `GET /connector-apps/{slug}` Read an app of the catalogue One app of the catalogue by its slug. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Path parameters** - `slug` (`string`, required): The slug of the app, such as `slack`. **Returns** - `200` `ConnectorApp`: The app. **Errors** - `503`: `connectors_unavailable` or `connector_provider_failed`. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.getApp()`](https://openemail.uk/docs/sdk/reference/connectors#getApp); Python [`connectors.get_app()`](https://openemail.uk/docs/python/reference/connectors#getApp); Ruby [`connectors.get_app`](https://openemail.uk/docs/ruby/reference/connectors#getApp); PHP [`connectors->getApp`](https://openemail.uk/docs/php/reference/connectors#getApp); Go [`Connectors.GetApp`](https://openemail.uk/docs/go/reference/connectors#getApp); Java [`connectors().getApp`](https://openemail.uk/docs/java/reference/connectors#getApp); C# [`Connectors.GetAppAsync`](https://openemail.uk/docs/csharp/reference/connectors#getApp); CLI [`openemail connectors get-app`](https://openemail.uk/docs/cli/reference/connectors#connectors-get-app); MCP [`getConnectorApp`](https://openemail.uk/docs/mcp/tools/connectors#getConnectorApp). ### `GET /connector-categories` List app categories The categories the catalogue sorts its apps into. Pass a `slug` from here as `category` when listing apps. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Returns** - `200` `ConnectorCategoryList`: The categories. **Errors** - `503`: `connectors_unavailable` or `connector_provider_failed`. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.listCategories()`](https://openemail.uk/docs/sdk/reference/connectors#listCategories); Python [`connectors.list_categories()`](https://openemail.uk/docs/python/reference/connectors#listCategories); Ruby [`connectors.list_categories`](https://openemail.uk/docs/ruby/reference/connectors#listCategories); PHP [`connectors->listCategories`](https://openemail.uk/docs/php/reference/connectors#listCategories); Go [`Connectors.ListCategories`](https://openemail.uk/docs/go/reference/connectors#listCategories); Java [`connectors().listCategories`](https://openemail.uk/docs/java/reference/connectors#listCategories); C# [`Connectors.ListCategoriesAsync`](https://openemail.uk/docs/csharp/reference/connectors#listCategories); CLI [`openemail connectors list-categories`](https://openemail.uk/docs/cli/reference/connectors#connectors-list-categories); MCP [`listConnectorApps`](https://openemail.uk/docs/mcp/tools/connectors#listConnectorApps). ### `GET /connectors` List connectors The connectors the caller can reach: the ones shared with the workspace, and its own. A connector that belongs to one person is reached only by an app that person connected, which also has to hold `account:read`, or `account:write` to change it. An API key acts for the workspace and reaches the shared connectors only. A key or an app limited to particular addresses or domains does not reach the shared ones. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Query parameters** - `scope` (`string`, one of `"account"`, `"workspace"`): `account` lists only the connectors that belong to the person the caller acts for, `workspace` only the shared ones. - `status` (`string`, one of `"pending"`, `"active"`, `"expired"`, `"paused"`): Only the connectors in this state. - `app` (`string`): Only the connectors of this app, by its slug. **Returns** - `200` `ConnectorList`: The connectors, by app. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.list()`](https://openemail.uk/docs/sdk/reference/connectors#list); Python [`connectors.list()`](https://openemail.uk/docs/python/reference/connectors#list); Ruby [`connectors.list`](https://openemail.uk/docs/ruby/reference/connectors#list); PHP [`connectors->list`](https://openemail.uk/docs/php/reference/connectors#list); Go [`Connectors.List`](https://openemail.uk/docs/go/reference/connectors#list); Java [`connectors().list`](https://openemail.uk/docs/java/reference/connectors#list); C# [`Connectors.ListAsync`](https://openemail.uk/docs/csharp/reference/connectors#list); CLI [`openemail connectors list`](https://openemail.uk/docs/cli/reference/connectors#connectors-list); MCP [`listConnectors`](https://openemail.uk/docs/mcp/tools/connectors#listConnectors). ### `POST /connectors` Connect an app Starts connecting an app and returns the connector with a `connectUrl`. A person has to open that link and sign in to the app there, or enter its key, on a page outside this API, so the secret never passes through the caller. Read the connector again afterwards: it is `active` once they have finished. With no `scope` the connector is shared with the workspace. A connector that belongs to one person is reached only by an app that person connected, which also has to hold `account:read`, or `account:write` to change it. An API key acts for the workspace and reaches the shared connectors only. A key or an app limited to particular addresses or domains does not reach the shared ones. A plan holds 2, 10 or 50 connectors for an account and as many again for a workspace. The largest plan sets no limit of its own, and nothing holds more than 200. Requires the `connectors:write` scope. - Scopes: `connectors:write`. **Request body** - `app` (`string`, required, 1 to 80 characters, pattern `^[a-z0-9][a-z0-9_-]*$`): The app to connect, by the slug the catalogue lists it under, such as `slack` or `notion`. - `scope` (`string`, one of `"account"`, `"workspace"`): Who the connector is for. `account` keeps it to one person. `workspace` shares it with the workspace, where tasks and anyone allowed to use connectors can reach it. Left out, it is `workspace`. - `label` (`string`, up to 80 characters): A name of your own for the connector, such as Sales Slack. Up to 80 characters. - `access` (`string`, one of `"read"`, `"full"`): What the assistant may do through it. `read` lets it look things up. `full` also lets it make changes, which it asks a person about first in chat and in tasks. Left out, it is `full`. **Returns** - `201` `ConnectorWithLink`: The connector, still `pending`, with its link. **Errors** - `403`: `insufficient_scope`: the key or app may not connect an app for that scope. `connector_limit_reached`: the plan holds no more connectors. - `404`: `connector_app_not_found`: the catalogue has no app with that slug. - `422`: `invalid_parameter`: a field is missing or malformed. `connector_app_unavailable`: the app cannot be connected yet. - `503`: `connectors_unavailable` or `connector_provider_failed`. - The errors every operation can return: `400`, `401`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.connect()`](https://openemail.uk/docs/sdk/reference/connectors#connect); Python [`connectors.connect()`](https://openemail.uk/docs/python/reference/connectors#connect); Ruby [`connectors.connect`](https://openemail.uk/docs/ruby/reference/connectors#connect); PHP [`connectors->connect`](https://openemail.uk/docs/php/reference/connectors#connect); Go [`Connectors.Connect`](https://openemail.uk/docs/go/reference/connectors#connect); Java [`connectors().connect`](https://openemail.uk/docs/java/reference/connectors#connect); C# [`Connectors.ConnectAsync`](https://openemail.uk/docs/csharp/reference/connectors#connect); CLI [`openemail connectors connect`](https://openemail.uk/docs/cli/reference/connectors#connectors-connect); MCP [`connectApp`](https://openemail.uk/docs/mcp/tools/connectors#connectApp). ### `GET /connectors/{id}` Read a connector One connector by its id, read fresh. While it is `pending` this also checks whether the sign-in was finished, so it is the call to make after sending somebody to `connectUrl`. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. **Returns** - `200` `Connector`: The connector. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.get()`](https://openemail.uk/docs/sdk/reference/connectors#get); Python [`connectors.get()`](https://openemail.uk/docs/python/reference/connectors#get); Ruby [`connectors.get`](https://openemail.uk/docs/ruby/reference/connectors#get); PHP [`connectors->get`](https://openemail.uk/docs/php/reference/connectors#get); Go [`Connectors.Get`](https://openemail.uk/docs/go/reference/connectors#get); Java [`connectors().get`](https://openemail.uk/docs/java/reference/connectors#get); C# [`Connectors.GetAsync`](https://openemail.uk/docs/csharp/reference/connectors#get); CLI [`openemail connectors get`](https://openemail.uk/docs/cli/reference/connectors#connectors-get); MCP [`getConnector`](https://openemail.uk/docs/mcp/tools/connectors#getConnector). ### `PATCH /connectors/{id}` Update a connector Renames a connector, pauses or resumes it, or changes its access. Send only what changes. A paused connector refuses every action until it is resumed. Requires the `connectors:write` scope. - Scopes: `connectors:write`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. **Request body** - `label` (`string`, nullable, up to 80 characters): A name of your own for the connector, such as Sales Slack. Up to 80 characters. - `access` (`string`, one of `"read"`, `"full"`): What the assistant may do through it. `read` lets it look things up. `full` also lets it make changes, which it asks a person about first in chat and in tasks. Left out, it is `full`. - `paused` (`boolean`): `true` stops every use of the connector until it is resumed. `false` resumes it. **Returns** - `200` `Connector`: The connector after the change. **Errors** - `403`: `insufficient_scope`: the key or app may not change this connector. `connector_limit_reached`: resuming it would go over what the plan holds. - `409`: `connector_not_active`: only an active connector can be paused. - `422`: `invalid_parameter`: nothing to change was sent, or a field is malformed. - The errors every operation can return: `400`, `401`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.update()`](https://openemail.uk/docs/sdk/reference/connectors#update); Python [`connectors.update()`](https://openemail.uk/docs/python/reference/connectors#update); Ruby [`connectors.update`](https://openemail.uk/docs/ruby/reference/connectors#update); PHP [`connectors->update`](https://openemail.uk/docs/php/reference/connectors#update); Go [`Connectors.Update`](https://openemail.uk/docs/go/reference/connectors#update); Java [`connectors().update`](https://openemail.uk/docs/java/reference/connectors#update); C# [`Connectors.UpdateAsync`](https://openemail.uk/docs/csharp/reference/connectors#update); CLI [`openemail connectors update`](https://openemail.uk/docs/cli/reference/connectors#connectors-update); MCP [`updateConnector`](https://openemail.uk/docs/mcp/tools/connectors#updateConnector). ### `DELETE /connectors/{id}` Disconnect an app Disconnects the app for good. The access it held in the outside app is given up there too, and its record of calls goes with it. A task that named the connector can no longer reach the app. Requires the `connectors:write` scope. - Scopes: `connectors:write`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. **Returns** - `200` `DeletedConnector`: Disconnected. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.disconnect()`](https://openemail.uk/docs/sdk/reference/connectors#disconnect); Python [`connectors.disconnect()`](https://openemail.uk/docs/python/reference/connectors#disconnect); Ruby [`connectors.disconnect`](https://openemail.uk/docs/ruby/reference/connectors#disconnect); PHP [`connectors->disconnect`](https://openemail.uk/docs/php/reference/connectors#disconnect); Go [`Connectors.Disconnect`](https://openemail.uk/docs/go/reference/connectors#disconnect); Java [`connectors().disconnect`](https://openemail.uk/docs/java/reference/connectors#disconnect); C# [`Connectors.DisconnectAsync`](https://openemail.uk/docs/csharp/reference/connectors#disconnect); CLI [`openemail connectors disconnect`](https://openemail.uk/docs/cli/reference/connectors#connectors-disconnect); MCP [`disconnectConnector`](https://openemail.uk/docs/mcp/tools/connectors#disconnectConnector). ### `POST /connectors/{id}/reconnect` Reconnect a connector Returns a fresh `connectUrl` for a connector that is `expired`, or whose first link ran out. A person has to open that link and sign in to the app there, or enter its key, on a page outside this API, so the secret never passes through the caller. Read the connector again afterwards: it is `active` once they have finished. The connector keeps its id, label and access. Requires the `connectors:write` scope. - Scopes: `connectors:write`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. **Returns** - `200` `ConnectorWithLink`: The connector with a fresh link. **Errors** - `422`: `connector_app_unavailable`: the app can no longer be connected. - `503`: `connectors_unavailable` or `connector_provider_failed`. - The errors every operation can return: `400`, `401`, `403`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.reconnect()`](https://openemail.uk/docs/sdk/reference/connectors#reconnect); Python [`connectors.reconnect()`](https://openemail.uk/docs/python/reference/connectors#reconnect); Ruby [`connectors.reconnect`](https://openemail.uk/docs/ruby/reference/connectors#reconnect); PHP [`connectors->reconnect`](https://openemail.uk/docs/php/reference/connectors#reconnect); Go [`Connectors.Reconnect`](https://openemail.uk/docs/go/reference/connectors#reconnect); Java [`connectors().reconnect`](https://openemail.uk/docs/java/reference/connectors#reconnect); C# [`Connectors.ReconnectAsync`](https://openemail.uk/docs/csharp/reference/connectors#reconnect); CLI [`openemail connectors reconnect`](https://openemail.uk/docs/cli/reference/connectors#connectors-reconnect); MCP [`reconnectConnector`](https://openemail.uk/docs/mcp/tools/connectors#reconnectConnector). ### `GET /connectors/{id}/actions` List what a connector can do The actions of the app behind a connector that match `search`, or its most used ones when `search` is left out. A connector set to `read` lists only the actions that read. Requires the `connectors:use` scope. - Scopes: `connectors:use`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. **Query parameters** - `search` (`string`): Words to look for in the name or the description. - `limit` (`integer`, at least 1, at most 30, default `12`): How many actions to return. **Returns** - `200` `ConnectorActionList`: The matching actions. **Errors** - `409`: `connector_not_active`: the connector is paused, pending or expired. - `503`: `connector_provider_failed`: the connection service did not answer. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.listActions()`](https://openemail.uk/docs/sdk/reference/connectors#listActions); Python [`connectors.list_actions()`](https://openemail.uk/docs/python/reference/connectors#listActions); Ruby [`connectors.list_actions`](https://openemail.uk/docs/ruby/reference/connectors#listActions); PHP [`connectors->listActions`](https://openemail.uk/docs/php/reference/connectors#listActions); Go [`Connectors.ListActions`](https://openemail.uk/docs/go/reference/connectors#listActions); Java [`connectors().listActions`](https://openemail.uk/docs/java/reference/connectors#listActions); C# [`Connectors.ListActionsAsync`](https://openemail.uk/docs/csharp/reference/connectors#listActions); CLI [`openemail connectors list-actions`](https://openemail.uk/docs/cli/reference/connectors#connectors-list-actions); MCP [`searchConnectorActions`](https://openemail.uk/docs/mcp/tools/connectors#searchConnectorActions). ### `GET /connectors/{id}/actions/{action}` Read an action One action with the input it takes, as a JSON Schema. Build the `input` of a run from it. Requires the `connectors:use` scope. - Scopes: `connectors:use`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. - `action` (`string`, required): The action, such as `SLACK_SEND_MESSAGE`, as the actions list of the connector names it. **Returns** - `200` `ConnectorActionDetail`: The action with its input schema. **Errors** - `409`: `connector_not_active`: the connector is paused, pending or expired. - `503`: `connector_provider_failed`: the connection service did not answer. - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.getAction()`](https://openemail.uk/docs/sdk/reference/connectors#getAction); Python [`connectors.get_action()`](https://openemail.uk/docs/python/reference/connectors#getAction); Ruby [`connectors.get_action`](https://openemail.uk/docs/ruby/reference/connectors#getAction); PHP [`connectors->getAction`](https://openemail.uk/docs/php/reference/connectors#getAction); Go [`Connectors.GetAction`](https://openemail.uk/docs/go/reference/connectors#getAction); Java [`connectors().getAction`](https://openemail.uk/docs/java/reference/connectors#getAction); C# [`Connectors.GetActionAsync`](https://openemail.uk/docs/csharp/reference/connectors#getAction); CLI [`openemail connectors get-action`](https://openemail.uk/docs/cli/reference/connectors#connectors-get-action); MCP [`getConnectorAction`](https://openemail.uk/docs/mcp/tools/connectors#getConnectorAction). ### `POST /connectors/{id}/actions/{action}/run` Run an action Runs one action in the connected app and returns what the app answered. An action that reads runs at once, and so does one that changes something: over the API nobody is asked first, so the caller decides. Inside the app the assistant asks a person before every change. A change made in the outside app cannot be taken back from here, and the call is not repeated when it fails. Every run is listed under `GET /connector-calls`, without its input or its result. Requires the `connectors:use` scope. - Scopes: `connectors:use`. **Path parameters** - `id` (`string`, required): The connector, such as `cnr_5c1e9a7b3d2f48e6a0b4c7d1`, as `GET /connectors` lists it. - `action` (`string`, required): The action, such as `SLACK_SEND_MESSAGE`, as the actions list of the connector names it. **Request body** - `input` (`Record`): The input of the action as an object, shaped as the input schema of that action describes. **Returns** - `200` `ConnectorRun`: The outcome. `ok` is false when the app itself refused the action. **Errors** - `403`: `connector_read_only`: the connector is set to `read` and the action changes something. - `409`: `connector_not_active`: the connector is paused, pending or expired. - `422`: `invalid_parameter`: `input` is not an object or is too large. `connector_action_failed`: the app refused the request as it was sent. - `503`: `connector_provider_failed`: the connection service did not answer. - The errors every operation can return: `400`, `401`, `404`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.runAction()`](https://openemail.uk/docs/sdk/reference/connectors#runAction); Python [`connectors.run_action()`](https://openemail.uk/docs/python/reference/connectors#runAction); Ruby [`connectors.run_action`](https://openemail.uk/docs/ruby/reference/connectors#runAction); PHP [`connectors->runAction`](https://openemail.uk/docs/php/reference/connectors#runAction); Go [`Connectors.RunAction`](https://openemail.uk/docs/go/reference/connectors#runAction); Java [`connectors().runAction`](https://openemail.uk/docs/java/reference/connectors#runAction); C# [`Connectors.RunActionAsync`](https://openemail.uk/docs/csharp/reference/connectors#runAction); CLI [`openemail connectors run-action`](https://openemail.uk/docs/cli/reference/connectors#connectors-run-action). ### `GET /connector-calls` List what was done through connectors Every action that ran through a connector the caller can reach, newest first: the app, the action, whether it read or changed something, whether it worked, and whether it came from chat, a task, the API or an agent. Inputs and results are never kept. Calls are kept 90 days. Requires the `connectors:read` scope. - Scopes: `connectors:read`. **Query parameters** - `connectorId` (`string`): Only the calls made through this connector. - `scope` (`string`, one of `"account"`, `"workspace"`): `account` lists only the connectors that belong to the person the caller acts for, `workspace` only the shared ones. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `ConnectorCallList`: A page of calls. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors). Also available in: TypeScript [`connectors.listCalls()`](https://openemail.uk/docs/sdk/reference/connectors#listCalls), [`connectors.listAllCalls()`](https://openemail.uk/docs/sdk/reference/connectors#listAllCalls), [`connectors.iterateCalls()`](https://openemail.uk/docs/sdk/reference/connectors#iterateCalls); Python [`connectors.list_calls()`](https://openemail.uk/docs/python/reference/connectors#listCalls), [`connectors.list_all_calls()`](https://openemail.uk/docs/python/reference/connectors#listAllCalls), [`connectors.iterate_calls()`](https://openemail.uk/docs/python/reference/connectors#iterateCalls); Ruby [`connectors.list_calls`](https://openemail.uk/docs/ruby/reference/connectors#listCalls), [`connectors.list_all_calls`](https://openemail.uk/docs/ruby/reference/connectors#listAllCalls), [`connectors.iterate_calls`](https://openemail.uk/docs/ruby/reference/connectors#iterateCalls); PHP [`connectors->listCalls`](https://openemail.uk/docs/php/reference/connectors#listCalls), [`connectors->listAllCalls`](https://openemail.uk/docs/php/reference/connectors#listAllCalls), [`connectors->iterateCalls`](https://openemail.uk/docs/php/reference/connectors#iterateCalls); Go [`Connectors.ListCalls`](https://openemail.uk/docs/go/reference/connectors#listCalls), [`Connectors.ListAllCalls`](https://openemail.uk/docs/go/reference/connectors#listAllCalls), [`Connectors.IterateCalls`](https://openemail.uk/docs/go/reference/connectors#iterateCalls); Java [`connectors().listCalls`](https://openemail.uk/docs/java/reference/connectors#listCalls), [`connectors().listAllCalls`](https://openemail.uk/docs/java/reference/connectors#listAllCalls), [`connectors().iterateCalls`](https://openemail.uk/docs/java/reference/connectors#iterateCalls); C# [`Connectors.ListCallsAsync`](https://openemail.uk/docs/csharp/reference/connectors#listCalls), [`Connectors.ListAllCallsAsync`](https://openemail.uk/docs/csharp/reference/connectors#listAllCalls), [`Connectors.IterateCallsAsync`](https://openemail.uk/docs/csharp/reference/connectors#iterateCalls); CLI [`openemail connectors list-calls`](https://openemail.uk/docs/cli/reference/connectors#connectors-list-calls); MCP [`listConnectorCalls`](https://openemail.uk/docs/mcp/tools/connectors#listConnectorCalls). ### Objects #### `Connector` `object` - `object` (`string`, required, one of `"connector"`) - `id` (`string`, required): The id, which starts with `cnr_`. - `scope` (`string`, required, one of `"account"`, `"workspace"`): `account` when it belongs to one person, `workspace` when it is shared with the workspace. - `app` (`string`, required): The slug of the connected app, such as `slack`. - `appName` (`string`, required): The name of the app, such as Slack. - `appLogo` (`string`, required, nullable): A link to the logo of the app. - `label` (`string`, required, nullable, up to 80 characters): The name the person gave the connector, if any. - `status` (`string`, required, one of `"pending"`, `"active"`, `"expired"`, `"paused"`): `pending` until the sign-in behind `connectUrl` 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 and it has to be reconnected. - `failure` (`string`, required, nullable, one of `"expired"`, `"revoked"`, `"failed"`, `"disabled"`): Why an `expired` connector stopped working: `expired` when the sign-in ran out, `revoked` when the access was taken away in the app, `failed` when the app refused the connection, `disabled` when the connection was switched off. - `pausedReason` (`string`, required, nullable, one of `"user"`, `"plan"`): `user` when a person paused it, `plan` when the workspace moved to a plan that holds fewer connectors. - `access` (`string`, required, one of `"read"`, `"full"`): `read` when the assistant may only look things up through it, `full` when it may also make changes. - `connectedAt` (`string`, required, nullable, format `date-time`): When the sign-in was last finished. - `lastUsedAt` (`string`, required, nullable, format `date-time`): When an action last ran through it. - `createdAt` (`string`, required, format `date-time`): When the connector was created. - `updatedAt` (`string`, required, format `date-time`): When it last changed. #### `ConnectorAction` `object` - `object` (`string`, required, one of `"connector_action"`) - `action` (`string`, required): The name to run the action by. - `name` (`string`, required): What the action is called. - `description` (`string`, required): What it does. - `kind` (`string`, required, one of `"read"`, `"change"`): `read` when it only looks something up, `change` when it creates, updates, sends or deletes something, or when the app does not say. #### `ConnectorActionDetail` `object` - `object` (`string`, required, one of `"connector_action"`) - `action` (`string`, required): The name to run the action by. - `name` (`string`, required): What the action is called. - `description` (`string`, required): What it does. - `kind` (`string`, required, one of `"read"`, `"change"`): `read` when it only looks something up, `change` when it creates, updates, sends or deletes something, or when the app does not say. - `input` (`object`, required): The input the action takes, as a JSON Schema. #### `ConnectorActionList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectorAction[]`) #### `ConnectorApp` `object` - `object` (`string`, required, one of `"connector_app"`) - `slug` (`string`, required): The slug to connect the app by. - `name` (`string`, required): What the app is called. - `description` (`string`, required): What the app is, in a sentence or two. - `logo` (`string`, required, nullable): A link to its logo. - `website` (`string`, required, nullable): The site of the app. - `categories` (`ConnectorCategory[]`, required) - `actions` (`integer`, required): How many actions the app offers. - `auth` (`string`, required, nullable, one of `"sign-in"`, `"key"`): `sign-in` when the person signs in to the app, `key` when they paste a key from it, and null when it cannot be connected yet. - `connectable` (`boolean`, required): Whether it can be connected today. #### `ConnectorAppList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectorApp[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `ConnectorCall` `object` - `object` (`string`, required, one of `"connector_call"`) - `id` (`string`, required): The id, which starts with `cnc_`. - `connectorId` (`string`, required): The connector the call went through. - `app` (`string`, required): The slug of the app. - `appName` (`string`, required): The name of the app. - `action` (`string`, required): The action that was run. - `kind` (`string`, required, one of `"read"`, `"change"`): Whether the action reads or changes something. - `status` (`string`, required, one of `"ok"`, `"failed"`, `"refused"`): `ok` when it ran, `failed` when the app or the connection refused it, `refused` when a rule here stopped it before it reached the app. - `errorCode` (`string`, required, nullable): The error code of a call that did not run, such as `connector_action_failed`. - `source` (`string`, required, one of `"chat"`, `"task"`, `"api"`, `"mcp"`): Where the call came from: `chat` for the assistant in the app, `task` for a task running by itself, `api` for this API and `mcp` for an agent on the MCP server. - `durationMs` (`integer`, required): How long the call took, in milliseconds. - `at` (`string`, required, format `date-time`): When it ran. #### `ConnectorCallList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectorCall[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `ConnectorCategory` `object` - `slug` (`string`, required): The value to pass as `category`. - `name` (`string`, required): What the category is called. #### `ConnectorCategoryList` `object` - `object` (`string`, one of `"list"`) - `data` (`ConnectorCategory[]`) #### `ConnectorList` `object` - `object` (`string`, one of `"list"`) - `data` (`Connector[]`) #### `ConnectorRun` `object` - `object` (`string`, required, one of `"connector_run"`) - `connectorId` (`string`, required): The connector the action ran through. - `app` (`string`, required): The slug of the app. - `action` (`string`, required): The action that ran. - `kind` (`string`, required, one of `"read"`, `"change"`): Whether the action reads or changes something. - `ok` (`boolean`, required): Whether the app carried the action out. - `data` (`any`, required): What the app answered, in its own shape. When `truncated` is true it is the start of that answer as text. - `error` (`string`, required, nullable): What the app said when `ok` is false. - `truncated` (`boolean`, required): Whether the answer was too long to return whole. #### `ConnectorWithLink` `object` - `object` (`string`, required, one of `"connector"`) - `id` (`string`, required): The id, which starts with `cnr_`. - `scope` (`string`, required, one of `"account"`, `"workspace"`): `account` when it belongs to one person, `workspace` when it is shared with the workspace. - `app` (`string`, required): The slug of the connected app, such as `slack`. - `appName` (`string`, required): The name of the app, such as Slack. - `appLogo` (`string`, required, nullable): A link to the logo of the app. - `label` (`string`, required, nullable, up to 80 characters): The name the person gave the connector, if any. - `status` (`string`, required, one of `"pending"`, `"active"`, `"expired"`, `"paused"`): `pending` until the sign-in behind `connectUrl` 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 and it has to be reconnected. - `failure` (`string`, required, nullable, one of `"expired"`, `"revoked"`, `"failed"`, `"disabled"`): Why an `expired` connector stopped working: `expired` when the sign-in ran out, `revoked` when the access was taken away in the app, `failed` when the app refused the connection, `disabled` when the connection was switched off. - `pausedReason` (`string`, required, nullable, one of `"user"`, `"plan"`): `user` when a person paused it, `plan` when the workspace moved to a plan that holds fewer connectors. - `access` (`string`, required, one of `"read"`, `"full"`): `read` when the assistant may only look things up through it, `full` when it may also make changes. - `connectedAt` (`string`, required, nullable, format `date-time`): When the sign-in was last finished. - `lastUsedAt` (`string`, required, nullable, format `date-time`): When an action last ran through it. - `createdAt` (`string`, required, format `date-time`): When the connector was created. - `updatedAt` (`string`, required, format `date-time`): When it last changed. - `connectUrl` (`string`, required, format `uri`): The page a person has to open to sign in to the app, or to enter its key. It is shown once, here. - `connectExpiresAt` (`string`, required, format `date-time`): When the link stops working. #### `DeletedConnector` `object` - `object` (`string`, required, one of `"connector"`) - `id` (`string`, required): The id of the connector that was disconnected. - `scope` (`string`, required, one of `"account"`, `"workspace"`): Whether it belonged to one person or to the workspace. - `app` (`string`, required): The slug of the app it connected. - `deleted` (`boolean`, required, one of `true`)