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.ListApps`

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

connectors:readPages through results

Signature

ListApps(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)

Returns one page of the catalogue of outside apps, the most used first. ListAllApps collects every page and IterateApps 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 openemail.WithSearch to find an app by its name or its description, or openemail.WithCategory 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.

Parameters

openemail.WithSearchstring: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
openemail.WithCategorystring: Only the apps in this category, by a slug that ListCategories returns.
openemail.WithLimitint: Page size, from 1 to 60. The server defaults to 24.
openemail.WithCursorstring: The NextCursor of the previous page, passed back as it came. Leave it out for the first page.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

A *openemail.Page with Items, HasMore and NextCursor. Each item has slug, name, description, logo, website, categories, actions, auth and connectable.

Example

page, err := client.Connectors.ListApps(ctx, openemail.WithSearch("calendar"), openemail.WithLimit(10))if err != nil {	return err} for _, app := range page.Items {	fmt.Println(app.String("slug"), app.String("name"), app.Int("actions"), app.Bool("connectable"))} fmt.Println(page.HasMore, page.NextCursor)

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 openemail.WithLimit asks for 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
Java: connectors().listApps
C#: Connectors.ListAppsAsync
CLI: openemail connectors list-apps

`Connectors.ListAllApps`

Collect every app that can be connected into one slice

connectors:readPages through results

Signature

ListAllApps(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)

Follows NextCursor from page to page and returns every app that matches, the most used first, in the shape ListApps returns. openemail.WithLimit sets the page size of each request, not the total. The whole catalogue is long, so give openemail.WithSearch or openemail.WithCategory, or prefer IterateApps when you do not need every app in memory.

Parameters

openemail.WithSearchstring: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
openemail.WithCategorystring: Only the apps in this category, by a slug that ListCategories returns.
openemail.WithLimitint: Page size for each request, from 1 to 60. The server defaults to 24.
openemail.WithCursorstring: Starts the walk after this cursor instead of the first page.
openemail.WithAPIKeystring: Overrides the client API key for every page of this walk.

Returns

A []openemail.Object holding every matching app across all pages.

Example

apps, err := client.Connectors.ListAllApps(ctx, openemail.WithCategory("productivity"), openemail.WithLimit(60))if err != nil {	return err} ready := 0 for _, app := range apps {	if app.Bool("connectable") {		ready++	}} fmt.Printf("%d of %d apps can be connected\n", ready, len(apps))

Notes

If any page fails the call fails 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
Java: connectors().listAllApps
C#: Connectors.ListAllAppsAsync

`Connectors.IterateApps`

Stream the apps that can be connected one at a time

connectors:readPages through results

Signature

IterateApps(ctx context.Context, opts ...openemail.RequestOption) *openemail.Iterator

Returns an iterator 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 you consume it, and breaking out of the loop stops the requests.

Parameters

openemail.WithSearchstring: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
openemail.WithCategorystring: Only the apps in this category, by a slug that ListCategories returns.
openemail.WithLimitint: Page size for each request, from 1 to 60. The server defaults to 24.
openemail.WithCursorstring: Starts the walk after this cursor instead of the first page.
openemail.WithAPIKeystring: Overrides the client API key for every page of this walk.

Returns

An *openemail.Iterator yielding one app per step.

Example

for app, err := range client.Connectors.IterateApps(ctx, openemail.WithSearch("notes")).All() {	if err != nil {		return err	} 	if !app.Bool("connectable") {		continue	} 	fmt.Println(app.String("slug"), app.String("name"), app.String("auth"))}

Notes

The iterator 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
Java: connectors().iterateApps
C#: Connectors.IterateAppsAsync

`Connectors.GetApp`

Read one app of the catalogue by its slug

connectors:read

Signature

GetApp(ctx context.Context, slug string, opts ...openemail.RequestOption) (openemail.Object, error)

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 set to false and auth set to null.

Parameters

slugstringRequired: The slug of the app, as ListApps returns it: letters, digits, hyphens and underscores, up to 80 characters. The case does not matter.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object with slug, name, description, logo, website, categories, actions, auth and connectable.

Example

app, err := client.Connectors.GetApp(ctx, "example-app")if err != nil {	return err} if app.Bool("connectable") {	fmt.Println(app.String("name"), "takes a", app.String("auth"), "and offers", app.Int("actions"), "actions")}

Notes

A slug the catalogue does not have fails with an *openemail.Error that matches openemail.ErrNotFound and code 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
Java: connectors().getApp
C#: Connectors.GetAppAsync
CLI: openemail connectors get-app

`Connectors.ListCategories`

List the categories the catalogue sorts its apps into

connectors:read

Signature

ListCategories(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)

Returns every category of the catalogue in one slice. The list comes whole and is never paged. Pass the slug of a category to ListApps with openemail.WithCategory to read only the apps in it. An app names the categories it sits in under categories.

Parameters

openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

A []openemail.Object. Each item has slug, the value to pass to openemail.WithCategory, and name.

Example

categories, err := client.Connectors.ListCategories(ctx)if err != nil {	return err} for _, category := range categories {	fmt.Println(category.String("slug"), category.String("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
Java: connectors().listCategories
C#: Connectors.ListCategoriesAsync
CLI: openemail connectors list-categories

`Connectors.List`

List the connectors the caller can reach

connectors:read

Signature

List(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)

Returns every connector the caller can reach in one slice, 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 openemail.WithScope, openemail.WithStatus or openemail.WithApp.

Parameters

openemail.WithScopestring: 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.
openemail.WithStatus...string: Only connectors in this state: pending, active, expired or paused.
openemail.WithAppstring: Only the connectors of this app, by its slug.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

A []openemail.Object. Each item has id, scope, app, appName, appLogo, label, status, failure, pausedReason, access, connectedAt, lastUsedAt, createdAt and updatedAt.

Example

connectors, err := client.Connectors.List(ctx, openemail.WithStatus("expired"))if err != nil {	return err} for _, connector := range connectors {	fmt.Println(connector.String("appName"), connector.String("label"), connector.String("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
Java: connectors().list
C#: Connectors.ListAsync
CLI: openemail connectors list

`Connectors.Get`

Read one connector by id

connectors:read

Signature

Get(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)

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.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object with id, scope, app, appName, appLogo, label, status, failure, pausedReason, access, connectedAt, lastUsedAt, createdAt and updatedAt.

Example

connector, err := client.Connectors.Get(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1")if err != nil {	return err} if connector.String("status") == "active" {	fmt.Println(connector.String("appName"), "is connected since", connector.String("connectedAt"))}

Notes

A missing connector, or one the caller cannot reach, fails with an *openemail.Error that matches openemail.ErrNotFound and code 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
Java: connectors().get
C#: Connectors.GetAsync
CLI: openemail connectors get

`Connectors.Connect`

Start connecting an app

connectors:write

Signature

Connect(ctx context.Context, body openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)

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 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 set to account keeps it to the person an app acts for.

Parameters

appstringRequired: The app to connect, by the slug that ListApps 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.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object: 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

connector, err := client.Connectors.Connect(ctx, openemail.Body{"app": "example-app", "label": "Team notes", "access": "read"})if err != nil {	return err} fmt.Println("Open this link and sign in:", connector.String("connectUrl")) fresh, err := client.Connectors.Get(ctx, connector.ID())if err != nil {	return err} fmt.Println(fresh.String("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. List with openemail.WithStatus("pending") shows a spare, and Disconnect removes it.

Also available in

API: POST /connectors
TypeScript: connectors.connect()
Python: connectors.connect()
Ruby: connectors.connect
PHP: connectors->connect
Java: connectors().connect
C#: Connectors.ConnectAsync
CLI: openemail connectors connect

`Connectors.Update`

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

connectors:write

Signature

Update(ctx context.Context, id string, patch openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)

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 RunAction 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 Reconnect.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
labelstring | nil: 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.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object with the unchanged id, and label, access, status and pausedReason as they are now.

Example

connector, err := client.Connectors.Update(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1", openemail.Body{"label": "Support desk", "access": "read"})if err != nil {	return err} fmt.Println(connector.String("label"), connector.String("access"), connector.String("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 Get before you try again.

Also available in

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

`Connectors.Disconnect`

Disconnect an app for good

connectors:write

Signature

Disconnect(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)

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

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object with object set to connector, the id, the scope, app, the slug of the app it connected, and deleted set to true.

Example

removed, err := client.Connectors.Disconnect(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1")if err != nil {	return err} fmt.Println(removed.String("app"), removed.Bool("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
Java: connectors().disconnect
C#: Connectors.DisconnectAsync
CLI: openemail connectors disconnect

`Connectors.Reconnect`

Get a fresh link to sign in to the app again

connectors:write

Signature

Reconnect(ctx context.Context, id string, opts ...openemail.RequestOption) (openemail.Object, error)

Returns 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.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object: 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

connector, err := client.Connectors.Reconnect(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1")if err != nil {	return err} fmt.Println("Open this link and sign in again:", connector.String("connectUrl"))fmt.Println("It works until", connector.String("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
Java: connectors().reconnect
C#: Connectors.ReconnectAsync
CLI: openemail connectors reconnect

`Connectors.ListActions`

List what a connector can do

connectors:use

Signature

ListActions(ctx context.Context, id string, opts ...openemail.RequestOption) ([]openemail.Object, error)

Returns the actions of the app behind a connector that match openemail.WithSearch, or its most used ones when openemail.WithSearch 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 openemail.WithSearch 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.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
openemail.WithSearchstring: 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.
openemail.WithLimitint: How many actions to return, from 1 to 30. The server defaults to 12.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

A []openemail.Object. Each item has action, name, description and kind.

Example

actions, err := client.Connectors.ListActions(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1", openemail.WithSearch("send message"), openemail.WithLimit(5))if err != nil {	return err} for _, action := range actions {	fmt.Println(action.String("action"), action.String("kind"), action.String("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
Java: connectors().listActions
C#: Connectors.ListActionsAsync
CLI: openemail connectors list-actions

`Connectors.GetAction`

Read one action with the input it takes

connectors:use

Signature

GetAction(ctx context.Context, id string, action string, opts ...openemail.RequestOption) (openemail.Object, error)

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.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
actionstringRequired: The name of the action, as ListActions returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object with action, name, description, kind and input, the JSON Schema of what the action takes.

Example

action, err := client.Connectors.GetAction(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1", "SEND_MESSAGE")if err != nil {	return err} fmt.Println(action.String("kind"), action.String("description")) schema, err := json.MarshalIndent(action["input"], "", "  ")if err != nil {	return err} fmt.Println(string(schema))

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
Java: connectors().getAction
C#: Connectors.GetActionAsync
CLI: openemail connectors get-action

`Connectors.RunAction`

Run one action in the connected app

connectors:use

Signature

RunAction(ctx context.Context, id string, action string, body openemail.Body, opts ...openemail.RequestOption) (openemail.Object, error)

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 map, shaped as the JSON Schema that GetAction returns for it. Pass nil as the 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 ListCalls, without its input and without its result.

Parameters

idstringRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as List returns it.
actionstringRequired: The name of the action, as ListActions returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
inputopenemail.Body: The input of the action as a map, shaped as GetAction describes it. Written as JSON it holds at most 60,000 characters. Left out, the action runs with no input.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

An openemail.Object 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

run, err := client.Connectors.RunAction(ctx, "cnr_5c1e9a7b3d2f48e6a0b4c7d1", "SEND_MESSAGE", openemail.Body{	"input": openemail.Body{"channel": "general", "text": "The report is ready."},})if err != nil {	return err} if run.Bool("ok") {	fmt.Println(run["data"])} else {	fmt.Println(run.String("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 map 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. Pass a longer openemail.WithTimeout 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. ListCalls with openemail.WithConnectorID 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
Java: connectors().runAction
C#: Connectors.RunActionAsync
CLI: openemail connectors run-action

`Connectors.ListCalls`

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

connectors:readPages through results

Signature

ListCalls(ctx context.Context, opts ...openemail.RequestOption) (*openemail.Page, error)

Returns one page of the record of calls, newest first: every action that ran through a connector the caller can reach. ListAllCalls collects every page and IterateCalls 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 openemail.WithConnectorID to read the calls of one connector, or openemail.WithScope to read only the calls of workspace connectors or only those of a person's own.

Parameters

openemail.WithConnectorIDstring: Only the calls made through this connector, by its id.
openemail.WithScopestring: Only the calls of one kind of connector: workspace or account. Left out, both are listed.
openemail.WithLimitint: Page size, from 1 to 100. The server defaults to 25.
openemail.WithCursorstring: The NextCursor of the previous page, passed back as it came. Leave it out for the first page.
openemail.WithAPIKeystring: Overrides the client API key for this call only.

Returns

A *openemail.Page with Items, HasMore and NextCursor. Each item has id, connectorId, app, appName, action, kind, status, errorCode, source, durationMs and at.

Example

page, err := client.Connectors.ListCalls(ctx, openemail.WithConnectorID("cnr_5c1e9a7b3d2f48e6a0b4c7d1"), openemail.WithLimit(50))if err != nil {	return err} for _, call := range page.Items {	fmt.Println(call.String("at"), call.String("action"), call.String("kind"), call.String("status"), call.String("source"))} fmt.Println(page.HasMore, page.NextCursor)

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. 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 RunAction, 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
Java: connectors().listCalls
C#: Connectors.ListCallsAsync
CLI: openemail connectors list-calls

`Connectors.ListAllCalls`

Collect every connector call into one slice

connectors:readPages through results

Signature

ListAllCalls(ctx context.Context, opts ...openemail.RequestOption) ([]openemail.Object, error)

Follows NextCursor from page to page and returns every call that matches, newest first, in the shape ListCalls returns. openemail.WithLimit sets the page size of each request, not the total. A busy workspace keeps a great many calls for its 90 days, so give openemail.WithConnectorID or openemail.WithScope, or prefer IterateCalls when you do not need them all in memory.

Parameters

openemail.WithConnectorIDstring: Only the calls made through this connector, by its id.
openemail.WithScopestring: Only the calls of one kind of connector: workspace or account. Left out, both are collected.
openemail.WithLimitint: Page size for each request, from 1 to 100. The server defaults to 25.
openemail.WithCursorstring: Starts the walk after this cursor instead of the first page.
openemail.WithAPIKeystring: Overrides the client API key for every page of this walk.

Returns

A []openemail.Object holding every matching call across all pages.

Example

calls, err := client.Connectors.ListAllCalls(ctx, openemail.WithConnectorID("cnr_5c1e9a7b3d2f48e6a0b4c7d1"), openemail.WithLimit(100))if err != nil {	return err} changes := 0 for _, call := range calls {	if call.String("kind") == "change" && call.String("status") == "ok" {		changes++	}} fmt.Printf("%d changes were made through this connector\n", changes)

Notes

If any page fails the call fails 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
Java: connectors().listAllCalls
C#: Connectors.ListAllCallsAsync

`Connectors.IterateCalls`

Stream the connector calls one at a time

connectors:readPages through results

Signature

IterateCalls(ctx context.Context, opts ...openemail.RequestOption) *openemail.Iterator

Returns an iterator that yields calls one by one, newest first, and requests the next page only once the current one is drained. Nothing is fetched until you consume it, and breaking out of the loop stops the requests.

Parameters

openemail.WithConnectorIDstring: Only the calls made through this connector, by its id.
openemail.WithScopestring: Only the calls of one kind of connector: workspace or account. Left out, both are walked.
openemail.WithLimitint: Page size for each request, from 1 to 100. The server defaults to 25.
openemail.WithCursorstring: Starts the walk after this cursor instead of the first page.
openemail.WithAPIKeystring: Overrides the client API key for every page of this walk.

Returns

An *openemail.Iterator yielding one call per step.

Example

for call, err := range client.Connectors.IterateCalls(ctx, openemail.WithScope("workspace")).All() {	if err != nil {		return err	} 	if call.String("status") == "ok" {		continue	} 	fmt.Println(call.String("at"), call.String("appName"), call.String("action"), call.String("status"), call.String("errorCode"))}

Notes

The iterator 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
Java: connectors().iterateCalls
C#: Connectors.IterateCallsAsync