client.Connectors

Every method in this namespace: its signature, its parameters, what it returns and an example.

Methods

Outside apps a person connects so the assistant can look things up in them and act there: browse the apps that can be connected, connect one for the workspace or for one person, rename, pause, reconnect and disconnect it, list what it can do, run one of its actions, and read the record of what was done through it.

`Connectors.ListAppsAsync`

List the apps that can be connected, a page at a time

connectors:readPages through results

Signature

Task<Page> ListAppsAsync(    string? search = null,    string? category = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the catalogue of outside apps, the most used first. ListAllAppsAsync collects every page and IterateAppsAsync walks them lazily. 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 ListCategoriesAsync 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 ConnectAsync.

Parameters

searchstring?: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystring?: Only the apps in this category, by a slug that ListCategoriesAsync returns.
limitint?: Page size, from 1 to 60. The server defaults to 24.
cursorstring?: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A Page with items, hasMore and nextCursor. Each item has slug, name, description, logo, website, categories, actions, auth and connectable.

Example

var page = await client.Connectors.ListAppsAsync(search: "calendar", limit: 10); foreach (var app in page){    Console.WriteLine($"{app["slug"]} {app["name"]}: {app["actions"]} actions, connectable: {app["connectable"]}");}

Notes

auth is sign-in when a person signs in to the app and key when they paste a key from it. It is null when the app cannot be connected yet, and connectable is then false.
A page can hold fewer apps than limit: and still have more after it, so follow hasMore, not the count.
The catalogue is the same for every caller, whatever addresses or domains a key or an app is limited to.
While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connector-apps
TypeScript: connectors.listApps()
Python: connectors.list_apps()
Ruby: connectors.list_apps
PHP: connectors->listApps
Go: Connectors.ListApps
Java: connectors().listApps
CLI: openemail connectors list-apps

`Connectors.ListAllAppsAsync`

Collect every app that can be connected into one list

connectors:readPages through results

Signature

Task<IReadOnlyList<JsonObject>> ListAllAppsAsync(    string? search = null,    string? category = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Follows nextCursor from page to page and returns every app that matches, the most used first, in the shape ListAppsAsync returns. limit: sets the page size of each request, not the total. The whole catalogue is long, so give search: or category:, or prefer IterateAppsAsync when you do not need every app in memory.

Parameters

searchstring?: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystring?: Only the apps in this category, by a slug that ListCategoriesAsync returns.
limitint?: Page size for each request, from 1 to 60. The server defaults to 24.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request in flight and the walk with it.

Returns

A list of JsonObject items holding every matching app across all pages.

Example

var apps = await client.Connectors.ListAllAppsAsync(category: "productivity", limit: 60);var ready = apps.Count(app => (bool?)app["connectable"] == true); Console.WriteLine($"{ready} of {apps.Count} apps can be connected");

Notes

If any page fails, the exception is thrown and the apps already fetched are discarded.
While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.

Also available in

API: GET /connector-apps
TypeScript: connectors.listAllApps()
Python: connectors.list_all_apps()
Ruby: connectors.list_all_apps
PHP: connectors->listAllApps
Go: Connectors.ListAllApps
Java: connectors().listAllApps

`Connectors.IterateAppsAsync`

Stream the apps that can be connected one at a time

connectors:readPages through results

Signature

IAsyncEnumerable<JsonObject> IterateAppsAsync(    string? search = null,    string? category = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> that yields apps one by one, the most used first, and requests the next page only once the current one is drained. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.

Parameters

searchstring?: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystring?: Only the apps in this category, by a slug that ListCategoriesAsync returns.
limitint?: Page size for each request, from 1 to 60. The server defaults to 24.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request in flight and the walk with it.

Returns

An IAsyncEnumerable<JsonObject> that yields one app per step.

Example

await foreach (var app in client.Connectors.IterateAppsAsync(search: "notes")){    if ((bool?)app["connectable"] != true)    {        continue;    }     Console.WriteLine($"{app["slug"]} {app["name"]} {app["auth"]}");}

Notes

The enumerable is lazy, so an abandoned loop costs only the pages you consumed.
While connectors are not switched on the first request is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.

Also available in

API: GET /connector-apps
TypeScript: connectors.iterateApps()
Python: connectors.iterate_apps()
Ruby: connectors.iterate_apps
PHP: connectors->iterateApps
Go: Connectors.IterateApps
Java: connectors().iterateApps

`Connectors.GetAppAsync`

Read one app of the catalogue by its slug

connectors:read

Signature

Task<JsonObject> GetAppAsync(    string slug,    string? apiKey = null,    CancellationToken cancellationToken = default)

Looks up one app of the catalogue and returns it in the same shape as a row of ListAppsAsync: 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 ConnectAsync. An app that is listed but cannot be connected yet has connectable set to false and auth set to null.

Parameters

slugstringRequired: The slug of the app, as ListAppsAsync returns it: letters, digits, hyphens and underscores, up to 80 characters. The case does not matter.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject with slug, name, description, logo, website, categories, actions, auth and connectable.

Example

var app = await client.Connectors.GetAppAsync("example-app"); if ((bool?)app["connectable"] == true){    Console.WriteLine($"{app["name"]} takes a {app["auth"]} and offers {app["actions"]} actions");}

Notes

A slug the catalogue does not have throws an OpenEmailApiException whose IsNotFound is true and whose Code is connector_app_not_found. A slug with other characters is 422 invalid_parameter.
auth is sign-in when a person signs in to the app and key when they paste a key from it.
While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connector-apps/{slug}
TypeScript: connectors.getApp()
Python: connectors.get_app()
Ruby: connectors.get_app
PHP: connectors->getApp
Go: Connectors.GetApp
Java: connectors().getApp
CLI: openemail connectors get-app

`Connectors.ListCategoriesAsync`

List the categories the catalogue sorts its apps into

connectors:read

Signature

Task<IReadOnlyList<JsonObject>> ListCategoriesAsync(    string? apiKey = null,    CancellationToken cancellationToken = default)

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

Parameters

apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A list of JsonObject items. Each item has slug, the value to pass as category:, and name.

Example

var categories = await client.Connectors.ListCategoriesAsync(); foreach (var category in categories){    Console.WriteLine($"{category["slug"]} {category["name"]}");}

Notes

While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connector-categories
TypeScript: connectors.listCategories()
Python: connectors.list_categories()
Ruby: connectors.list_categories
PHP: connectors->listCategories
Go: Connectors.ListCategories
Java: connectors().listCategories
CLI: openemail connectors list-categories

`Connectors.ListAsync`

List the connectors the caller can reach

connectors:read

Signature

Task<IReadOnlyList<JsonObject>> ListAsync(    string? scope = null,    string? status = null,    string? app = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns every connector the caller can reach in one list, 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:.

Parameters

scopestring?: Only one kind of connector: workspace for the ones shared with the workspace, account for the ones that belong to the person an app acts for. Left out, both are listed.
statusstring?: Only connectors in this state: pending, active, expired or paused.
appstring?: Only the connectors of this app, by its slug.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A list of JsonObject items. Each item has id, scope, app, appName, appLogo, label, status, failure, pausedReason, access, connectedAt, lastUsedAt, createdAt and updatedAt.

Example

using OpenEmail.Constants; var connectors = await client.Connectors.ListAsync(status: ConnectorStatuses.Expired); foreach (var connector in connectors){    Console.WriteLine($"{connector["appName"]} {connector["label"]} stopped working: {connector["failure"]}");}

Notes

failure says why a connector stopped working: expired, revoked, failed or disabled. It is null while nothing is wrong. pausedReason is user when a person paused the connector and plan when the workspace moved to a plan that holds fewer connectors.
app is the slug of the connected app and appName its name. label is the name a person gave the connector, or null. connectedAt is when the sign-in was last finished and lastUsedAt when an action last ran through it.
An API key acts for the workspace and reaches the connectors of the workspace only. A connector that belongs to one person is reached only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace, so it is given none of them.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connectors
TypeScript: connectors.list()
Python: connectors.list()
Ruby: connectors.list
PHP: connectors->list
Go: Connectors.List
Java: connectors().list
CLI: openemail connectors list

`Connectors.GetAsync`

Read one connector by id

connectors:read

Signature

Task<JsonObject> GetAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Looks up one connector and returns it in the same shape as a row of ListAsync, read fresh. While a sign-in is still open, after ConnectAsync or ReconnectAsync, 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 ConnectAsync.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject with id, scope, app, appName, appLogo, label, status, failure, pausedReason, access, connectedAt, lastUsedAt, createdAt and updatedAt.

Example

using OpenEmail.Constants; var connector = await client.Connectors.GetAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1"); if ((string?)connector["status"] == ConnectorStatuses.Active){    Console.WriteLine($"{connector["appName"]} is connected since {connector["connectedAt"]}");}

Notes

A missing connector, or one the caller cannot reach, throws an OpenEmailApiException whose IsNotFound is true and whose Code is connector_not_found.
An API key acts for the workspace and reaches the connectors of the workspace only. A connector that belongs to one person is reached only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connectors/{id}
TypeScript: connectors.get()
Python: connectors.get()
Ruby: connectors.get
PHP: connectors->get
Go: Connectors.Get
Java: connectors().get
CLI: openemail connectors get

`Connectors.ConnectAsync`

Start connecting an app

connectors:write

Signature

Task<JsonObject> ConnectAsync(    IReadOnlyDictionary<string, object?> body,    string? apiKey = null,    CancellationToken cancellationToken = default)

Starts connecting an app and returns the new connector with 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 GetAsync: 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 ReconnectAsync 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 set to account keeps it to the person an app acts for.

Parameters

appstringRequired: The app to connect, by the slug that ListAppsAsync returns.
scopestring: Who the connector is for. workspace shares it with the workspace and is the default. account keeps it to the person connecting it, which only an app that person connected may ask for.
labelstring: A name of your own for the connector, trimmed, up to 80 characters. Left out, it has none.
accessstring: What the assistant may do through the connector. read lets it look things up. full also lets it make changes and is the default.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject: the connector with a new id and status pending, plus connectUrl, the page to send the person to, and connectExpiresAt, when that link stops working.

Example

using OpenEmail.Constants; var connector = await client.Connectors.ConnectAsync(new Body{    ["app"] = "example-app",    ["label"] = "Team notes",    ["access"] = ConnectorAccessLevels.Read,}); Console.WriteLine($"Open this link and sign in: {connector["connectUrl"]}"); var fresh = await client.Connectors.GetAsync(connector["id"]!.GetValue<string>()); Console.WriteLine($"{fresh["appName"]} is {fresh["status"]}");

Notes

A workspace holds 2 connectors on Free, 10 on Starter and 50 on Business, with no cap on Enterprise, and at most 200 whatever the plan. A person holds as many again of their own. One more is refused with 403 connector_limit_reached, and a connector that is still pending counts.
An app the catalogue does not have is a 404 connector_app_not_found, and one that cannot be connected yet a 422 connector_app_unavailable. A field of the wrong type or length is 422 invalid_parameter, and a key the body does not take 422 unknown_parameter.
An API key acts for the workspace, so it connects an app for the workspace only. scope set to account needs an app the person connected, holding account:write beside connectors:write. Anything else is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace, so it cannot connect an app for it.
While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer. Nothing is created either way.
Not retried automatically: every call makes another connector with a link of its own, so a retry after a lost response can leave two. ListAsync with status: set to pending shows a spare, and DisconnectAsync removes it.

Also available in

API: POST /connectors
TypeScript: connectors.connect()
Python: connectors.connect()
Ruby: connectors.connect
PHP: connectors->connect
Go: Connectors.Connect
Java: connectors().connect
CLI: openemail connectors connect

`Connectors.UpdateAsync`

Rename a connector, pause or resume it, or change its access

connectors:write

Signature

Task<JsonObject> UpdateAsync(    string id,    IReadOnlyDictionary<string, object?> patch,    string? apiKey = null,    CancellationToken cancellationToken = default)

Changes a connector and returns 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 set to true stops the assistant, tasks and RunActionAsync from using the connector until paused set to 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 or an empty string takes its name away.

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

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
labelstring: A name of your own for the connector, trimmed, up to 80 characters. Null or an empty string clears it. Left out, the name stays.
accessstring: read lets the assistant only look things up through the connector. full also lets it make changes. Left out, it stays.
pausedbool: True pauses the connector and false resumes it. Left out, it stays as it is.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject with the unchanged id, and label, access, status and pausedReason as they are now.

Example

using OpenEmail.Constants; var connector = await client.Connectors.UpdateAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1", new Body{    ["label"] = "Support desk",    ["access"] = ConnectorAccessLevels.Read,}); Console.WriteLine($"{connector["label"]} {connector["access"]} {connector["status"]}");

Notes

Pausing a connector that is pending or expired answers 409 connector_not_active. Pausing one that is already paused leaves it paused, with pausedReason as it was.
Resuming a connector the plan paused is refused with 403 connector_limit_reached while the plan covers no more connectors. A connector whose sign-in stopped working comes back as expired, not active.
An empty patch or a value of the wrong type or length is 422 invalid_parameter, and a key the patch does not take 422 unknown_parameter. A missing connector is a 404 connector_not_found.
An API key acts for the workspace and changes the connectors of the workspace only. A connector that belongs to one person is changed only by an app that person connected, which also needs account:write. Without it the call is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
Not retried automatically. A retry that arrives after somebody else changed the connector would make the change a second time, such as pausing a connector that was just resumed. Read it with GetAsync before you try again.

Also available in

API: PATCH /connectors/{id}
TypeScript: connectors.update()
Python: connectors.update()
Ruby: connectors.update
PHP: connectors->update
Go: Connectors.Update
Java: connectors().update
CLI: openemail connectors update

`Connectors.DisconnectAsync`

Disconnect an app for good

connectors:write

Signature

Task<JsonObject> DisconnectAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

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 UpdateAsync with paused set to true. To use the app again later, start over with ConnectAsync.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject with object set to connector, the id, the scope, app, the slug of the app it connected, and deleted set to true.

Example

var removed = await client.Connectors.DisconnectAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1"); Console.WriteLine($"{removed["app"]} deleted: {removed["deleted"]}");

Notes

A missing connector, or one the caller cannot reach, is a 404 connector_not_found.
An API key acts for the workspace and disconnects the connectors of the workspace only. A connector that belongs to one person is disconnected only by an app that person connected, which also needs account:write. Without it the call is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
The SDK retries this call after a network failure. When the first attempt went through and only its answer was lost, the retry answers 404 connector_not_found, which then means the connector is gone.

Also available in

API: DELETE /connectors/{id}
TypeScript: connectors.disconnect()
Python: connectors.disconnect()
Ruby: connectors.disconnect
PHP: connectors->disconnect
Go: Connectors.Disconnect
Java: connectors().disconnect
CLI: openemail connectors disconnect

`Connectors.ReconnectAsync`

Get a fresh link to sign in to the app again

connectors:write

Signature

Task<JsonObject> ReconnectAsync(    string id,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns a fresh connectUrl for a connector that is expired, or that is still pending because nobody finished its first link. As with ConnectAsync, 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 GetAsync 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.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject: the connector with its unchanged id and its status as it is now, plus a new connectUrl and connectExpiresAt, when that link stops working.

Example

var connector = await client.Connectors.ReconnectAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1"); Console.WriteLine($"Open this link and sign in again: {connector["connectUrl"]}");Console.WriteLine($"It works until {connector["connectExpiresAt"]}");

Notes

The link works for at most 30 minutes and only this answer shows it. A new link replaces the one before it, which no longer connects anything.
A missing connector is a 404 connector_not_found, and an app that can no longer be connected a 422 connector_app_unavailable.
An API key acts for the workspace and reconnects the connectors of the workspace only. A connector that belongs to one person is reconnected only by an app that person connected, which also needs account:write. Without it the call is refused with 403 insufficient_scope.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
While connectors are not switched on the call is refused with 503 connectors_unavailable, and with 503 connector_provider_failed when the connection service does not answer.
Not retried automatically: every call makes a second link and the one before it no longer connects anything, so a retry after a lost response could cancel a link somebody is already using.

Also available in

API: POST /connectors/{id}/reconnect
TypeScript: connectors.reconnect()
Python: connectors.reconnect()
Ruby: connectors.reconnect
PHP: connectors->reconnect
Go: Connectors.Reconnect
Java: connectors().reconnect
CLI: openemail connectors reconnect

`Connectors.ListActionsAsync`

List what a connector can do

connectors:use

Signature

Task<IReadOnlyList<JsonObject>> ListActionsAsync(    string id,    string? search = null,    int? limit = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns 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. GetActionAsync adds the input an action takes.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
searchstring?: Words to look for in the name or the description of an action, trimmed, up to 200 characters. Left out, the most used actions are listed.
limitint?: How many actions to return, from 1 to 30. The server defaults to 12.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A list of JsonObject items. Each item has action, name, description and kind.

Example

var actions = await client.Connectors.ListActionsAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1", search: "send message", limit: 5); foreach (var action in actions){    Console.WriteLine($"{action["action"]} {action["kind"]} {action["name"]}");}

Notes

The connector has to be active. One that is paused, pending or expired answers 409 connector_not_active, and a missing one 404 connector_not_found.
An API key acts for the workspace and uses the connectors of the workspace only. A connector that belongs to one person is used only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
When the connection service does not answer the call is refused with 503 connector_provider_failed.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connectors/{id}/actions
TypeScript: connectors.listActions()
Python: connectors.list_actions()
Ruby: connectors.list_actions
PHP: connectors->listActions
Go: Connectors.ListActions
Java: connectors().listActions
CLI: openemail connectors list-actions

`Connectors.GetActionAsync`

Read one action with the input it takes

connectors:use

Signature

Task<JsonObject> GetActionAsync(    string id,    string action,    string? apiKey = null,    CancellationToken cancellationToken = default)

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

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
actionstringRequired: The name of the action, as ListActionsAsync returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A JsonObject with action, name, description, kind and input, the JSON Schema of what the action takes.

Example

var action = await client.Connectors.GetActionAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1", "SEND_MESSAGE"); Console.WriteLine($"{action["kind"]} {action["description"]}");Console.WriteLine(action["input"]?.ToJsonString());

Notes

An action the app does not have is a 404 connector_action_not_found, and a name with other characters a 422 invalid_parameter.
The connector has to be active. One that is paused, pending or expired answers 409 connector_not_active, and a missing one 404 connector_not_found.
An API key acts for the workspace and uses the connectors of the workspace only. A connector that belongs to one person is used only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
When the connection service does not answer the call is refused with 503 connector_provider_failed.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connectors/{id}/actions/{action}
TypeScript: connectors.getAction()
Python: connectors.get_action()
Ruby: connectors.get_action
PHP: connectors->getAction
Go: Connectors.GetAction
Java: connectors().getAction
CLI: openemail connectors get-action

`Connectors.RunActionAsync`

Run one action in the connected app

connectors:use

Signature

Task<JsonObject> RunActionAsync(    string id,    string action,    IReadOnlyDictionary<string, object?>? body = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Runs one action in the app behind a connector 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. 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 a dictionary, shaped as the JSON Schema that GetActionAsync returns for it. Call it with no body for an action that takes none.

The call returns 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 ListCallsAsync, without its input and without its result.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as ListAsync returns it.
actionstringRequired: The name of the action, as ListActionsAsync returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
inputdictionary: The input of the action as a dictionary, shaped as GetActionAsync describes it. Written as JSON it holds at most 60,000 characters. Left out, the action runs with no input.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request. The action may still run in the app.

Returns

A JsonObject with connectorId, app, action, kind, ok, data, error and truncated. data is what the app answered, in its own shape. When truncated is true the answer was too long to return whole, and data is the start of it as text. error is null when ok is true.

Example

var run = await client.Connectors.RunActionAsync("cnr_5c1e9a7b3d2f48e6a0b4c7d1", "SEND_MESSAGE", new Body{    ["input"] = new Body { ["channel"] = "general", ["text"] = "The report is ready." },}); if ((bool?)run["ok"] == true){    Console.WriteLine(run["data"]?.ToJsonString());}else{    Console.WriteLine($"The app refused: {run["error"]}");}

Notes

A connector whose access is read refuses an action that changes something with 403 connector_read_only. A connector that is paused, pending or expired answers 409 connector_not_active, and a missing one 404 connector_not_found.
An action the app does not have is a 404 connector_action_not_found. An input that is not a dictionary or is too large is 422 invalid_parameter, and a key the body does not take 422 unknown_parameter. A request the app refuses as it was sent, most often because input does not match what the action takes, is 422 connector_action_failed with what the app said in the message.
An action may take up to a minute. The client stops waiting after its Timeout, 30 seconds unless you set another, and the action can still finish in the app after that. Create the client with a longer Timeout for slow actions.
A 503 connector_provider_failed means the connection service did not answer in time. The app may still have carried the action out, so look in the app before you run it again.
An API key acts for the workspace and uses the connectors of the workspace only. A connector that belongs to one person is used only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace.
Not retried automatically: a retry after a lost response could make the same change twice. ListCallsAsync with connectorId: shows the run once it has ended.

Also available in

API: POST /connectors/{id}/actions/{action}/run
TypeScript: connectors.runAction()
Python: connectors.run_action()
Ruby: connectors.run_action
PHP: connectors->runAction
Go: Connectors.RunAction
Java: connectors().runAction
CLI: openemail connectors run-action

`Connectors.ListCallsAsync`

List what was done through connectors, a page at a time

connectors:readPages through results

Signature

Task<Page> ListCallsAsync(    string? connectorId = null,    string? scope = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns one page of the record of calls, newest first: every action that ran through a connector the caller can reach. ListAllCallsAsync collects every page and IterateCallsAsync walks them lazily. 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 connectorId: 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.

Parameters

connectorIdstring?: Only the calls made through this connector, by its id.
scopestring?: Only the calls of one kind of connector: workspace or account. Left out, both are listed.
limitint?: Page size, from 1 to 100. The server defaults to 25.
cursorstring?: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
apiKeystring?: Overrides the client's API key for this call only.
cancellationTokenCancellationToken: Cancels the request.

Returns

A Page with items, hasMore and nextCursor. Each item has id, connectorId, app, appName, action, kind, status, source, durationMs and at, plus the error code, read with call["errorCode"].

Example

var page = await client.Connectors.ListCallsAsync(connectorId: "cnr_5c1e9a7b3d2f48e6a0b4c7d1", limit: 50); foreach (var call in page){    Console.WriteLine($"{call["at"]} {call["action"]} {call["kind"]} {call["status"]} {call["source"]}");}

Notes

status is ok when the action ran, failed when the app or the connection refused it, and refused when a rule here stopped it before it reached the app, such as a change through a connector set to read. The error code, read with call["errorCode"], names the reason and is null on an ok call.
source is chat for the assistant in a conversation, task for a task run, api for a call over the API such as RunActionAsync, and mcp for an agent.
An API key acts for the workspace and reads the calls of workspace connectors only. The calls of a connector that belongs to one person are read only by an app that person connected, which also needs account:read.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace, so it is given none of their calls.
The cursor is opaque and holds where the last row sat in this order, so a call made between pages never breaks the walk. One that cannot be read is a 400 invalid_cursor.
Read only, so the SDK retries it after a network failure like any other read.

Also available in

API: GET /connector-calls
TypeScript: connectors.listCalls()
Python: connectors.list_calls()
Ruby: connectors.list_calls
PHP: connectors->listCalls
Go: Connectors.ListCalls
Java: connectors().listCalls
CLI: openemail connectors list-calls

`Connectors.ListAllCallsAsync`

Collect every connector call into one list

connectors:readPages through results

Signature

Task<IReadOnlyList<JsonObject>> ListAllCallsAsync(    string? connectorId = null,    string? scope = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Follows nextCursor from page to page and returns every call that matches, newest first, in the shape ListCallsAsync returns. limit: sets the page size of each request, not the total. A busy workspace keeps a great many calls for its 90 days, so give connectorId: or scope:, or prefer IterateCallsAsync when you do not need them all in memory.

Parameters

connectorIdstring?: Only the calls made through this connector, by its id.
scopestring?: Only the calls of one kind of connector: workspace or account. Left out, both are collected.
limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request in flight and the walk with it.

Returns

A list of JsonObject items holding every matching call across all pages.

Example

using OpenEmail.Constants; var calls = await client.Connectors.ListAllCallsAsync(connectorId: "cnr_5c1e9a7b3d2f48e6a0b4c7d1", limit: 100);var changes = calls.Count(call => (string?)call["kind"] == ConnectorActionKinds.Change && (string?)call["status"] == ConnectorCallStatuses.Ok); Console.WriteLine($"{changes} changes were made through this connector");

Notes

If any page fails, the exception is thrown and the calls already fetched are discarded.
A call record holds no input and no result, and calls older than 90 days are gone.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace, so it is given none of their calls.

Also available in

API: GET /connector-calls
TypeScript: connectors.listAllCalls()
Python: connectors.list_all_calls()
Ruby: connectors.list_all_calls
PHP: connectors->listAllCalls
Go: Connectors.ListAllCalls
Java: connectors().listAllCalls

`Connectors.IterateCallsAsync`

Stream the connector calls one at a time

connectors:readPages through results

Signature

IAsyncEnumerable<JsonObject> IterateCallsAsync(    string? connectorId = null,    string? scope = null,    int? limit = null,    string? cursor = null,    string? apiKey = null,    CancellationToken cancellationToken = default)

Returns an IAsyncEnumerable<JsonObject> that yields calls one by one, newest first, and requests the next page only once the current one is drained. Nothing is fetched until the loop starts, and breaking out of the await foreach stops the requests.

Parameters

connectorIdstring?: Only the calls made through this connector, by its id.
scopestring?: Only the calls of one kind of connector: workspace or account. Left out, both are walked.
limitint?: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstring?: Starts the walk after this cursor instead of the first page.
apiKeystring?: Overrides the client's API key for every page of this walk.
cancellationTokenCancellationToken: Cancels the request in flight and the walk with it.

Returns

An IAsyncEnumerable<JsonObject> that yields one call per step.

Example

using OpenEmail.Constants; await foreach (var call in client.Connectors.IterateCallsAsync(scope: ConnectorScopes.Workspace)){    if ((string?)call["status"] == ConnectorCallStatuses.Ok)    {        continue;    }     Console.WriteLine($"{call["at"]} {call["appName"]} {call["action"]} {call["status"]}: {call["errorCode"]}");}

Notes

The enumerable is lazy, so an abandoned loop costs only the pages you consumed.
A key or an app limited to particular addresses or domains does not reach the connectors of the workspace, so it is given none of their calls.

Also available in

API: GET /connector-calls
TypeScript: connectors.iterateCalls()
Python: connectors.iterate_calls()
Ruby: connectors.iterate_calls
PHP: connectors->iterateCalls
Go: Connectors.IterateCalls
Java: connectors().iterateCalls