---
title: "Connect or reconnect an app"
description: "Starts connecting an app and returns the connector with the link a person finishes on. Reconnecting returns a fresh link for a connector that stopped working."
url: "https://openemail.uk/docs/api/connectors/connect"
area: "API"
category: "Mailbox"
---

# Connect or reconnect an app

Starts connecting an app and returns the connector with the link a person finishes on. Reconnecting returns a fresh link for a connector that stopped working.

`POST /connectors`

**Also documents:** `POST /connectors/{id}/reconnect`

## POST /connectors

Starts connecting an app and returns the connector with the link a person finishes on. Reconnecting returns a fresh link for a connector that stopped working.

## Example

Both need `connectors:write`. Only `app` is required. Left out, `scope` is `workspace` and `access` is `full`.

**curl**

```
curl -X POST "$OE/connectors" -H "$AUTH" -H 'content-type: application/json' -d '{
  "app": "slack",
  "scope": "workspace",
  "label": "Sales Slack",
  "access": "read"
}'
curl -X POST "$OE/connectors/cnr_5c1e9a7b3d2f48e6a0b4c7d1/reconnect" -H "$AUTH"
```

**Response**

```
{
  "object": "connector",
  "id": "cnr_5c1e9a7b3d2f48e6a0b4c7d1",
  "scope": "workspace",
  "app": "slack",
  "appName": "Slack",
  "appLogo": "https://logos.example.com/slack.png",
  "label": "Sales Slack",
  "status": "pending",
  "failure": null,
  "pausedReason": null,
  "access": "read",
  "connectedAt": null,
  "lastUsedAt": null,
  "createdAt": "2026-10-13T09:12:44.000Z",
  "updatedAt": "2026-10-13T09:12:44.000Z",
  "connectUrl": "https://connect.example.com/link/lk_5Qm2x8RtVn",
  "connectExpiresAt": "2026-10-13T09:42:44.000Z"
}
```

> A person has to open `connectUrl` and sign in to the app there, or enter its key. That page is outside this API, so the password or key never passes through the caller. The link is returned once and works until `connectExpiresAt`.

> The connector is `pending` until they have finished. Read it again with `GET /connectors/{id}`, and it is `active` once they have.

> `"scope": "account"` connects the app for one person, so it takes an app that person connected, holding `account:write`. An API key connects for the workspace only, and answers 403 `insufficient_scope` otherwise.

> Reconnecting is for a connector that is `expired`, or whose first link ran out. It keeps its id, its label and its access.

> A slug that names no app answers 404 `connector_app_not_found`, an app that cannot be connected yet 422 `connector_app_unavailable`, and a plan that holds no more connectors 403 `connector_limit_reached`.

## Reference

- [`POST /connectors`](https://openemail.uk/docs/api/reference/connectors#post-connectors): full reference
- [`POST /connectors/{id}/reconnect`](https://openemail.uk/docs/api/reference/connectors#post-connectors-id-reconnect): full reference