Python

openemail.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.list_apps()`

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

connectors:readPages through results

Signature

def list_apps(    *,    limit: int | None = None,    cursor: str | None = None,    search: str | None = None,    category: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[ConnectorAppResource]

Returns one page of the catalogue of outside apps, the most used first. list_all_apps collects every page and iterate_apps 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 list_categories 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

limitint: Page size, from 1 to 60. The server defaults to 24.
cursorstr: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
searchstr: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystr: Only the apps in this category, by a slug that list_categories returns.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Page[ConnectorAppResource], a dict with items, hasMore and nextCursor. Each item has slug, name, description, logo, website, categories, actions, auth and connectable.

Example

from openemail import openemail page = openemail.connectors.list_apps(search='calendar', limit=10) for app in page['items']:    print(app['slug'], app['name'], app['actions'], 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 None 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()
Ruby: connectors.list_apps
PHP: connectors->listApps
Go: Connectors.ListApps
Java: connectors().listApps
C#: Connectors.ListAppsAsync
CLI: openemail connectors list-apps

`connectors.list_all_apps()`

Collect every app that can be connected into one list

connectors:readPages through results

Signature

def list_all_apps(    *,    limit: int | None = None,    cursor: str | None = None,    search: str | None = None,    category: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[ConnectorAppResource]

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

Parameters

limitint: Page size for each request, from 1 to 60. The server defaults to 24.
cursorstr: Starts the walk after this cursor instead of the first page.
searchstr: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystr: Only the apps in this category, by a slug that list_categories returns.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[ConnectorAppResource] holding every matching app across all pages.

Example

from openemail import openemail apps = openemail.connectors.list_all_apps(category='productivity', limit=60) ready = [app for app in apps if app['connectable']] print(f'{len(ready)} of {len(apps)} apps can be connected')

Notes

If any page fails, the call raises 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()
Ruby: connectors.list_all_apps
PHP: connectors->listAllApps
Go: Connectors.ListAllApps
Java: connectors().listAllApps
C#: Connectors.ListAllAppsAsync

`connectors.iterate_apps()`

Stream the apps that can be connected one at a time

connectors:readPages through results

Signature

def iterate_apps(    *,    limit: int | None = None,    cursor: str | None = None,    search: str | None = None,    category: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[ConnectorAppResource]

Returns a generator 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

limitint: Page size for each request, from 1 to 60. The server defaults to 24.
cursorstr: Starts the walk after this cursor instead of the first page.
searchstr: Words to look for in the name or the description of an app, trimmed, up to 200 characters.
categorystr: Only the apps in this category, by a slug that list_categories returns.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Iterator[ConnectorAppResource], a generator yielding one app per step.

Example

from openemail import openemail for app in openemail.connectors.iterate_apps(search='notes'):    if not app['connectable']:        continue     print(app['slug'], app['name'], app['auth'])

Notes

The generator 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()
Ruby: connectors.iterate_apps
PHP: connectors->iterateApps
Go: Connectors.IterateApps
Java: connectors().iterateApps
C#: Connectors.IterateAppsAsync

`connectors.get_app()`

Read one app of the catalogue by its slug

connectors:read

Signature

def get_app(    slug: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorAppResource

Looks up one app of the catalogue and returns it in the same shape as a row of list_apps: 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 None.

Parameters

slugstrRequired: The slug of the app, as list_apps returns it: letters, digits, hyphens and underscores, up to 80 characters. The case does not matter.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Example

from openemail import openemail app = openemail.connectors.get_app('example-app') if app['connectable']:    print(app['name'], 'takes a', app['auth'], 'and offers', app['actions'], 'actions')

Notes

A slug the catalogue does not have raises OpenEmailApiError with is_not_found set to True 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()
Ruby: connectors.get_app
PHP: connectors->getApp
Go: Connectors.GetApp
Java: connectors().getApp
C#: Connectors.GetAppAsync
CLI: openemail connectors get-app

`connectors.list_categories()`

List the categories the catalogue sorts its apps into

connectors:read

Signature

def list_categories(    *,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[ConnectorCategoryResource]

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 list_apps to read only the apps in it. An app names the categories it sits in under categories.

Parameters

api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[ConnectorCategoryResource]. Each item has slug, the value to pass as category=, and name.

Example

from openemail import openemail categories = openemail.connectors.list_categories() for category in categories:    print(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()
Ruby: connectors.list_categories
PHP: connectors->listCategories
Go: 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

def list(    *,    scope: ConnectorScope | None = None,    status: ConnectorStatus | None = None,    app: str | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[ConnectorResource]

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

scopeConnectorScope: 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.
statusConnectorStatus: Only connectors in this state: pending, active, expired or paused.
appstr: Only the connectors of this app, by its slug.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Example

from openemail import openemail connectors = openemail.connectors.list(status='expired') for connector in connectors:    print(connector['appName'], connector['label'], connector['failure'])

Notes

failure says why a connector stopped working: expired, revoked, failed or disabled. It is None 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 None. 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()
Ruby: connectors.list
PHP: connectors->list
Go: Connectors.List
Java: connectors().list
C#: Connectors.ListAsync
CLI: openemail connectors list

`connectors.get()`

Read one connector by id

connectors:read

Signature

def get(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorResource

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

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Example

from openemail import openemail connector = openemail.connectors.get('cnr_5c1e9a7b3d2f48e6a0b4c7d1') if connector['status'] == 'active':    print(connector['appName'], 'is connected since', connector['connectedAt'])

Notes

A missing connector, or one the caller cannot reach, raises OpenEmailApiError with is_not_found set to True 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()
Ruby: connectors.get
PHP: connectors->get
Go: Connectors.Get
Java: connectors().get
C#: Connectors.GetAsync
CLI: openemail connectors get

`connectors.connect()`

Start connecting an app

connectors:write

Signature

def connect(    body: ConnectorConnect,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorLinkResource

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

body['app']strRequired: The app to connect, by the slug that list_apps returns.
body['scope']ConnectorScope: 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.
body['label']str: A name of your own for the connector, trimmed, up to 80 characters. Left out, it has none.
body['access']ConnectorAccess: What the assistant may do through the connector. read lets it look things up. full also lets it make changes and is the default.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

ConnectorLinkResource: 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

from openemail import openemail connector = openemail.connectors.connect(    {'app': 'example-app', 'label': 'Team notes', 'access': 'read'}) print('Open this link and sign in:', connector['connectUrl']) fresh = openemail.connectors.get(connector['id']) print(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. list with status='pending' shows a spare, and disconnect removes it.

Also available in

API: POST /connectors
TypeScript: connectors.connect()
Ruby: connectors.connect
PHP: connectors->connect
Go: 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

def update(    id: str,    patch: ConnectorPatch,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorResource

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 run_action 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 None or an empty string takes its name away.

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

Parameters

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
patch['label']str | None: A name of your own for the connector, trimmed, up to 80 characters. None or an empty string clears it. Left out, the name stays.
patch['access']ConnectorAccess: read lets the assistant only look things up through the connector. full also lets it make changes. Left out, it stays.
patch['paused']bool: True pauses the connector and False resumes it. Left out, it stays as it is.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Example

from openemail import openemail connector = openemail.connectors.update(    'cnr_5c1e9a7b3d2f48e6a0b4c7d1',    {'label': 'Support desk', 'access': 'read'},) print(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 get before you try again.

Also available in

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

`connectors.disconnect()`

Disconnect an app for good

connectors:write

Signature

def disconnect(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> DeletedConnectorResource

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

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

DeletedConnectorResource, a dict with object set to connector, the id, the scope, app, the slug of the app it connected, and deleted set to True.

Example

from openemail import openemail removed = openemail.connectors.disconnect('cnr_5c1e9a7b3d2f48e6a0b4c7d1') print(removed['app'], 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()
Ruby: connectors.disconnect
PHP: connectors->disconnect
Go: 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

def reconnect(    id: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorLinkResource

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

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

ConnectorLinkResource: 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

from openemail import openemail connector = openemail.connectors.reconnect('cnr_5c1e9a7b3d2f48e6a0b4c7d1') print('Open this link and sign in again:', connector['connectUrl'])print('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()
Ruby: connectors.reconnect
PHP: connectors->reconnect
Go: Connectors.Reconnect
Java: connectors().reconnect
C#: Connectors.ReconnectAsync
CLI: openemail connectors reconnect

`connectors.list_actions()`

List what a connector can do

connectors:use

Signature

def list_actions(    id: str,    *,    search: str | None = None,    limit: int | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[ConnectorActionResource]

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

Parameters

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
searchstr: 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.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[ConnectorActionResource]. Each item has action, name, description and kind.

Example

from openemail import openemail actions = openemail.connectors.list_actions(    'cnr_5c1e9a7b3d2f48e6a0b4c7d1',    search='send message',    limit=5,) for action in actions:    print(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()
Ruby: connectors.list_actions
PHP: connectors->listActions
Go: Connectors.ListActions
Java: connectors().listActions
C#: Connectors.ListActionsAsync
CLI: openemail connectors list-actions

`connectors.get_action()`

Read one action with the input it takes

connectors:use

Signature

def get_action(    id: str,    action: str,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorActionDetailResource

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

Parameters

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
actionstrRequired: The name of the action, as list_actions returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

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

Example

import json from openemail import openemail action = openemail.connectors.get_action('cnr_5c1e9a7b3d2f48e6a0b4c7d1', 'SEND_MESSAGE') print(action['kind'], action['description'])print(json.dumps(action['input'], indent=2))

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

`connectors.run_action()`

Run one action in the connected app

connectors:use

Signature

def run_action(    id: str,    action: str,    body: ConnectorActionRun | None = None,    *,    api_key: str | None = None,    timeout: float | None = None,) -> ConnectorRunResource

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 dict, shaped as the JSON Schema that get_action 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 list_calls, without its input and without its result.

Parameters

idstrRequired: Connector id such as cnr_5c1e9a7b3d2f48e6a0b4c7d1, as list returns it.
actionstrRequired: The name of the action, as list_actions returns it in action: letters, digits and underscores, up to 160 characters. The case does not matter.
body['input']dict[str, Any]: The input of the action as a dict, shaped as get_action describes it. Written as JSON it holds at most 60,000 characters. Left out, the action runs with no input.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

ConnectorRunResource 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 None when ok is True.

Example

from openemail import openemail run = openemail.connectors.run_action(    'cnr_5c1e9a7b3d2f48e6a0b4c7d1',    'SEND_MESSAGE',    {'input': {'channel': 'general', 'text': 'The report is ready.'}},) if run['ok']:    print(run['data'])else:    print(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 dict 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 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. list_calls with connector_id= shows the run once it has ended.

Also available in

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

`connectors.list_calls()`

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

connectors:readPages through results

Signature

def list_calls(    *,    limit: int | None = None,    cursor: str | None = None,    connector_id: str | None = None,    scope: ConnectorScope | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Page[ConnectorCallResource]

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

Parameters

limitint: Page size, from 1 to 100. The server defaults to 25.
cursorstr: The nextCursor of the previous page, passed back as it came. Leave it out for the first page.
connector_idstr: Only the calls made through this connector, by its id.
scopeConnectorScope: Only the calls of one kind of connector: workspace or account. Left out, both are listed.
api_keystr: Overrides the client API key for this call only.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Page[ConnectorCallResource], a dict with items, hasMore and nextCursor. Each item has id, connectorId, app, appName, action, kind, status, errorCode, source, durationMs and at.

Example

from openemail import openemail page = openemail.connectors.list_calls(connector_id='cnr_5c1e9a7b3d2f48e6a0b4c7d1', limit=50) for call in page['items']:    print(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. errorCode names the reason and is None 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 run_action, 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()
Ruby: connectors.list_calls
PHP: connectors->listCalls
Go: Connectors.ListCalls
Java: connectors().listCalls
C#: Connectors.ListCallsAsync
CLI: openemail connectors list-calls

`connectors.list_all_calls()`

Collect every connector call into one list

connectors:readPages through results

Signature

def list_all_calls(    *,    limit: int | None = None,    cursor: str | None = None,    connector_id: str | None = None,    scope: ConnectorScope | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> builtins.list[ConnectorCallResource]

Follows nextCursor from page to page and returns every call that matches, newest first, in the shape list_calls 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 connector_id= or scope=, or prefer iterate_calls when you do not need them all in memory.

Parameters

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
connector_idstr: Only the calls made through this connector, by its id.
scopeConnectorScope: Only the calls of one kind of connector: workspace or account. Left out, both are collected.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

list[ConnectorCallResource] holding every matching call across all pages.

Example

from openemail import openemail calls = openemail.connectors.list_all_calls(    connector_id='cnr_5c1e9a7b3d2f48e6a0b4c7d1',    limit=100,) changes = [call for call in calls if call['kind'] == 'change' and call['status'] == 'ok'] print(f'{len(changes)} changes were made through this connector')

Notes

If any page fails, the call raises 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()
Ruby: connectors.list_all_calls
PHP: connectors->listAllCalls
Go: Connectors.ListAllCalls
Java: connectors().listAllCalls
C#: Connectors.ListAllCallsAsync

`connectors.iterate_calls()`

Stream the connector calls one at a time

connectors:readPages through results

Signature

def iterate_calls(    *,    limit: int | None = None,    cursor: str | None = None,    connector_id: str | None = None,    scope: ConnectorScope | None = None,    api_key: str | None = None,    timeout: float | None = None,) -> Iterator[ConnectorCallResource]

Returns a generator 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

limitint: Page size for each request, from 1 to 100. The server defaults to 25.
cursorstr: Starts the walk after this cursor instead of the first page.
connector_idstr: Only the calls made through this connector, by its id.
scopeConnectorScope: Only the calls of one kind of connector: workspace or account. Left out, both are walked.
api_keystr: Overrides the client API key for every page of this walk.
timeoutfloat: Seconds this call may take, the response included, before it raises OpenEmailNetworkError with is_timeout. It overrides the client's timeout for this call, and 0 turns the limit off.

Returns

Iterator[ConnectorCallResource], a generator yielding one call per step.

Example

from openemail import openemail for call in openemail.connectors.iterate_calls(scope='workspace'):    if call['status'] == 'ok':        continue     print(call['at'], call['appName'], call['action'], call['status'], call['errorCode'])

Notes

The generator 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()
Ruby: connectors.iterate_calls
PHP: connectors->iterateCalls
Go: Connectors.IterateCalls
Java: connectors().iterateCalls
C#: Connectors.IterateCallsAsync