---
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://nextmail.sh/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**

```
nextmail connectors list-apps --search slack
nextmail connectors connect --app slack --scope workspace --label "Sales Slack" --access read
nextmail connectors get cnr_5c1e9a7b3d2f48e6a0b4c7d1
nextmail connectors list-actions cnr_5c1e9a7b3d2f48e6a0b4c7d1 --search "search messages"
nextmail 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 |
| --- | --- |
| nextmail connectors list-apps | One page of the apps that can be connected, most used first. `--search` and `--category` narrow it |
| nextmail 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 |
| nextmail connectors list-categories | The categories the apps are sorted into, to pass as `--category` |

## Connectors

| Command | What it does |
| --- | --- |
| nextmail connectors list | The connectors you can reach. `--scope`, `--status` and `--app` narrow it |
| nextmail 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` |
| nextmail connectors get <id> | One connector, read fresh. While it is `pending` this also checks whether the sign-in was finished |
| nextmail connectors update <id> | Rename it with `--label`, change `--access`, or pause and resume it with `--paused` and `--no-paused` |
| nextmail connectors reconnect <id> | Print a fresh link for a connector that is `expired`, or whose first link ran out. It keeps its id |
| nextmail connectors disconnect <id> | Disconnect the app for good, once you confirm. The access it held in the outside app is given up too |

**Terminal**

```
nextmail connectors list --scope workspace --status expired
nextmail connectors reconnect cnr_5c1e9a7b3d2f48e6a0b4c7d1
nextmail connectors update cnr_5c1e9a7b3d2f48e6a0b4c7d1 --access full
nextmail connectors update cnr_5c1e9a7b3d2f48e6a0b4c7d1 --paused
nextmail 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 |
| --- | --- |
| nextmail 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 |
| nextmail connectors get-action <id> <action> | One action with the input it takes, as a JSON Schema |
| nextmail 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 `-` |
| nextmail connectors list-calls | What was done through the connectors, newest first. `--connector-id` and `--scope` narrow it |

**Terminal**

```
nextmail connectors get-action cnr_5c1e9a7b3d2f48e6a0b4c7d1 SLACK_SEND_MESSAGE --json
nextmail connectors run-action cnr_5c1e9a7b3d2f48e6a0b4c7d1 SLACK_SEND_MESSAGE --action-input @message.json
nextmail 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.