---
title: "Connectors"
description: "Every command for connectors, the apps that can be connected, the actions they offer and the record of what was done, with worked examples."
url: "https://openemail.uk/docs/cli/connectors"
area: "CLI"
category: "Commands by area"
---

# Connectors

Every command for connectors, the apps that can be connected, the actions they offer and the record of what was done, with worked examples.

## How it fits together

A connector is an outside app, such as Slack or Notion, connected so the assistant can look things up in it and act there. It belongs to one person or to the workspace, and it lets the assistant only read or also make changes. Reading needs `connectors:read`, looking up and running actions needs `connectors:use`, and connecting, changing and disconnecting need `connectors:write`.

**Terminal**

```
openemail connectors list-apps --search slack
openemail connectors connect --app slack --scope workspace --label "Sales Slack" --access read
openemail connectors get cnr_5c1e9a7b3d2f48e6a0b4c7d1
openemail connectors list-actions cnr_5c1e9a7b3d2f48e6a0b4c7d1 --search "search messages"
openemail connectors run-action cnr_5c1e9a7b3d2f48e6a0b4c7d1 SLACK_SEARCH_MESSAGES --action-input '{"query":"renewal"}'
```

`connect` prints a link. Open it in a browser and sign in to the app there, or paste its key, so the secret never passes through the command line. The connector is `pending` until you have finished, and `get` shows it turn `active`. An API key reaches workspace connectors only, and a browser sign-in also reaches your own.

## Apps that can be connected

| Command | What it does |
| --- | --- |
| openemail connectors list-apps | One page of the apps that can be connected, most used first. `--search` and `--category` narrow it |
| openemail connectors get-app <slug> | One app: what it is, whether it connects by a sign-in or a key, and how many actions it has |
| openemail connectors list-categories | The categories the apps are sorted into, to pass as `--category` |

## Connectors

| Command | What it does |
| --- | --- |
| openemail connectors list | The connectors you can reach. `--scope`, `--status` and `--app` narrow it |
| openemail connectors connect --app <slug> | Start connecting an app and print the link to finish on. `--scope` is `workspace` or `account`, and `--access` is `full` or `read`. Left out, they are `workspace` and `full` |
| openemail connectors get <id> | One connector, read fresh. While it is `pending` this also checks whether the sign-in was finished |
| openemail connectors update <id> | Rename it with `--label`, change `--access`, or pause and resume it with `--paused` and `--no-paused` |
| openemail connectors reconnect <id> | Print a fresh link for a connector that is `expired`, or whose first link ran out. It keeps its id |
| openemail connectors disconnect <id> | Disconnect the app for good, once you confirm. The access it held in the outside app is given up too |

**Terminal**

```
openemail connectors list --scope workspace --status expired
openemail connectors reconnect cnr_5c1e9a7b3d2f48e6a0b4c7d1
openemail connectors update cnr_5c1e9a7b3d2f48e6a0b4c7d1 --access full
openemail connectors update cnr_5c1e9a7b3d2f48e6a0b4c7d1 --paused
openemail connectors disconnect cnr_5c1e9a7b3d2f48e6a0b4c7d1 --yes
```

A connector is `pending` until its 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. A paused connector refuses every action until it is resumed. `--yes` skips the confirmation in a script.

## Actions and calls

| Command | What it does |
| --- | --- |
| openemail connectors list-actions <id> | What the app can do that matches `--search`, or its most used actions. Each says whether it reads or changes something |
| openemail connectors get-action <id> <action> | One action with the input it takes, as a JSON Schema |
| openemail connectors run-action <id> <action> | Run the action, once you confirm, and print what the app answered. `--action-input` takes its input as JSON, inline, from a file with `@path` or from standard input with `-` |
| openemail connectors list-calls | What was done through the connectors, newest first. `--connector-id` and `--scope` narrow it |

**Terminal**

```
openemail connectors get-action cnr_5c1e9a7b3d2f48e6a0b4c7d1 SLACK_SEND_MESSAGE --json
openemail connectors run-action cnr_5c1e9a7b3d2f48e6a0b4c7d1 SLACK_SEND_MESSAGE --action-input @message.json
openemail connectors list-calls --connector-id cnr_5c1e9a7b3d2f48e6a0b4c7d1 --all --json
```

The server asks nobody before an action that changes something runs, so `run-action` asks you to confirm, and `--yes` skips that in a script. Check the input against `get-action` first, because a change in the outside app cannot be taken back. A connector set to `read` refuses a change. Calls are kept for 90 days, without their input or their result.