openemail connectors

Resolves one page of the catalogue of outside apps, the most used first. A connector links one of these apps to the workspace, or to one person, so the assistant can look things up in the app and act there.

Give search to find an app by its name or its description, or category to read one category, by a slug that listCategories returns. Each app says how many actions it offers in actions, how a person signs in to it in auth, and in connectable whether it can be connected today. Pass its slug to connect.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Looks up one app of the catalogue and returns it in the same shape as a row of listApps: its name and description, its logo and website, the categories it sits in, how many actions it offers and how a person signs in to it.

Read connectable before you call connect. An app that is listed but cannot be connected yet has connectable false and auth null.

Resolves every category of the catalogue in one array. The list comes whole and is never paged. Pass the slug of a category as category to listApps to read only the apps in it. An app names the categories it sits in under categories.

Resolves every connector the caller can reach in one array, by scope and then by the name of the app. The list comes whole and is never paged. A connector is one outside app that somebody connected, so the assistant can look things up in it and act there. It belongs to the workspace, where tasks and everyone allowed to use connectors reach it, or to one person. scope says which: workspace or account.

status is pending until the person has finished signing in to the app, 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. access is read when the assistant may only look things up through the connector and full when it may also make changes.

Narrow the list with scope, status or app.

Looks up one connector and returns it in the same shape as a row of list, read fresh. While a sign-in is still open, after connect or reconnect, the call also checks whether the person has finished it. So this is the call to make after sending somebody to connectUrl: status is active once they are done.

A connector that is still pending when its link runs out is removed, and so is one whose sign-in failed. The call then answers 404 connector_not_found. Start over with connect.

Starts connecting an app and resolves with the new connector and a connectUrl. A person has to open that link and sign in to the app there, or enter its key. That happens on a page outside this API, so the secret never passes through the caller. Until they have finished, the connector is pending and nothing can run through it. Read it again with get: status is active once they are done.

The link works until connectExpiresAt, at most 30 minutes, and only this answer shows it. A connector that is still pending when its link runs out is removed. Until then reconnect gives it a fresh link.

With no scope the connector is shared with the workspace, where tasks and everyone allowed to use connectors reach it. scope: 'account' keeps it to the person an app acts for.

Changes a connector and resolves with it as it is stored. Send only what changes: a field left out stays as it is, and a patch with nothing in it is a 422.

paused: true stops the assistant, tasks and runAction from using the connector until paused: false resumes it. Only an active connector can be paused. access switches between read, where only actions that look something up may run, and full. label renames the connector, and null takes its name away.

It does not sign in again. A connector that is expired needs reconnect.

Disconnects the app and removes the connector for good. The access it held in the outside app is given up there too, and the record of the calls made through it goes with it. A task that named the connector can no longer reach the app.

There is no undo. To stop a connector and keep it, use update with paused: true. To use the app again later, start over with connect.

Resolves with a fresh connectUrl for a connector that is expired, or that is still pending because nobody finished its first link. As with connect, a person has to open the link and sign in to the app there, or enter its key, on a page outside this API. Read the connector again with get afterwards: it is active once they are done.

The connector keeps its id, label and access. The answer shows it as it is now, before anybody has signed in again, and a connector that still works keeps working on its old sign-in until the new one is finished. It takes no body.

Resolves the actions of the app behind a connector that match search, or its most used ones when search is left out. An action is one thing the app can do, such as finding a record or sending a message. Each one has the name to run it by in action, what it is called in name, what it does in description, and its 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.

The list is not paged and holds at most 30 actions, so use search to find one that is not among the first. A connector whose access is read lists only the actions that read. getAction adds the input an action takes.

Looks up one action of the app behind a connector and returns it as listActions does, with input added: the input the action takes, as a JSON Schema. Build the input of runAction from it. kind says whether running the action only reads or changes something in the app.

Runs one action in the app behind a connector and resolves with 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. In the OpenEmail app the assistant asks a person before every change. A change made in the outside app cannot be taken back from here.

input is the input of the action as an object, shaped as the JSON Schema that getAction returns for it. Call it with no body for an action that takes none.

The promise resolves whether or not the app carried the action out. ok is true when it did, with the answer of the app in data. When the app itself refuses, ok is false and error holds what it said. Every run is listed by listCalls, without its input and without its result.

Resolves one page of the record of calls, newest first: every action that ran through a connector the caller can reach. Each call names the connector and its app, the action, whether it read or changed something in kind, how it ended in status, where it came from in source and how long it took in durationMs.

A call record holds no input and no result. Those are never kept. Calls are kept for 90 days, and the calls of a connector go with it when it is disconnected.

Give --connector-id to read the calls of one connector, or scope to read only the calls of workspace connectors or only those of a person's own.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.