openemail knowledge

Resolves one page of the knowledge base, newest first: the notes, files and web pages the AI uses when it writes replies, drafts email and answers in the assistant. Each item says where it sits, whether the AI can use it yet and how much text was read from it.

Every item sits at one level, its scope: an empty string for the whole workspace, @ and a domain for everything on that domain (@acme.com), or one address ([email protected]). The AI writing for an address reads that address, then its domain, then the whole workspace, the most specific first. level names the kind of level, workspace, domain or address.

status is queued or processing while the text is read and indexed, ready once the AI can use it, and failed with a failure when it could not be read. A key or an app limited to particular addresses sees the whole-workspace items and the items at its addresses and at their domains.

Each item also says how the AI uses it: uses counts the times it came up in a reply suggestion, a draft, the assistant or a search, with lastUsedAt the latest, and flags counts the open duplicate and conflict flags that name it. A link read again on a schedule has refreshDays and nextRefreshAt, a page kept by a connector names it in connectorId, and a note saved from a conversation names it in threadId.

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

Resolves every level the caller can see: the whole workspace first, then each domain, then each address, with how many items each holds and whether the caller may add and change items there. Pass its scope when you add an item.

A key or an app limited to particular addresses sees the whole workspace, its addresses and their domains. writable is true at the whole workspace only for a caller that reaches every address, at a domain for one that holds the whole domain, and at an address for one that holds that address.

Resolves how many items and how many characters of text the workspace keeps in its knowledge base, beside what its plan allows in limits: 50 items and 1,000,000 characters on Free, 500 and 10,000,000 on Starter, 2,000 and 50,000,000 on Business, and 10,000 and 200,000,000 on Enterprise.

An item counts as soon as it is added, and its characters once its text has been read. The numbers are for the whole workspace, whatever the key may reach.

Resolves the passages that best answer query, best first, found by meaning and by words the way the AI finds them when it writes. Each hit names the item it comes from in sourceId, with its title, kind, level and link, the headings the passage sits under and the passage itself.

With address, it searches the levels the AI uses for that address: the address, its domain and the whole workspace, the most specific ranked a little higher. With scope, it searches that one level, and scope wins when both are given. With neither, it searches every level the caller can see.

With rerank: true, the AI reads the best 25 passages and puts them in the order that best answers query, leaving out the ones that do not help. It adds a second or two and counts as one AI action, and reranked says whether it happened: when it cannot finish, the passages keep their usual order and reranked is false.

Saves a note of up to 20,000 characters at one level and resolves with it. Markdown is kept, and its headings become the headings the passages sit under. A note is usually ready for the AI within a second or two, and queued or processing until then.

pinned: true puts the note into every prompt the AI writes at its level, not only when it matches what is being written. The AI reads at most 2,000 characters of pinned notes from each level, so keep them short.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.

Adds a public web page at one level and resolves with it, queued. The page is fetched and read in the background, and the AI uses it once its status is ready. Without a title, the item is named after the link until the page is read, and then after the page's own title.

url is a public http or https address of at most 2,048 characters, and it is kept as https. An address on a private or local host, or one with a user name, a password or a port, is refused. A level holds a page once, and refresh fetches it again after it changes. With --refresh-days, the page is also read again every 1, 7 or 30 days on its own, nextRefreshAt says when, and a changed page reaches the AI without a call.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.

Stores a document or an image at one level and resolves with it, queued. Its text is read in the background, and the AI uses it once its status is ready. PDFs, Word documents, spreadsheets (Excel, OpenDocument, Numbers and CSV), OpenDocument text, HTML, XML, Markdown, plain text, JSON and images (JPEG, PNG, WebP and SVG) can be read.

data is a Blob, an ArrayBuffer or a Uint8Array, sent as the request body. The name travels as the filename query parameter, and the type is --content-type, a Blob's own type when that is left out, or the extension of the name when the type is generic. A document can be up to 20 MB and an image up to 10 MB.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.

Resolves one item with its text: the body of a note, or in preview the first 20,000 characters read from a file or a page, with previewTruncated true when the text goes on past it. preview is null while a file or a page has not been read yet, and body is null for anything but a note.

Changes the title of an item, the text of a note, the page of a link, how often a link is read again, whether a note is pinned, or its level, and resolves with the item as it is now. Give at least one field. A changed title, text or link is read and indexed again, so the item goes back to queued, and its previous text stays in use until the new one is ready. Moving an item to another level needs no new reading.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole. Moving an item needs that reach at both levels.

Removes an item with its file and every passage read from it, and the AI stops using it at once. There is no undo.

Fetches a link again, reads a file again or indexes a note again, clears any failure and resolves with the item, back at queued. Use it after a page changed or when an item failed. The previous text stays in use until the new one is ready.

Resolves how the AI used the knowledge base over the last days days, today included, 30 unless you say. uses counts the times a reply suggestion, a draft, the assistant or a search found something in it, and empty the times it looked and found nothing. coverage is uses divided by the two together, from 0 to 1, and 0 when it never looked. bySurface splits uses by where they happened, under the keys compose, reply, chat, tool and search, and series has one entry per day, oldest first, days with nothing included.

topItems lists the items used most, ever, and unusedItems counts the ready items the AI has never used. pendingSuggestions counts the learned notes waiting for review, openQuestions the questions senders asked that nothing answers yet, and openFlags the open duplicate and conflict flags. uses, empty, bySurface and series cover the whole workspace, while the items, suggestions, questions and flags count only what the caller can see.

Resolves one page of what the AI suggests adding to the knowledge base, the most recent first, pending ones unless you ask for another status.

A learned suggestion is a note the AI drew from a reply sent from the workspace: it reads the message the reply answers and the reply, and keeps up to three facts that would hold for other people too, at the level of the domain the reply was sent from, or the whole workspace when that domain is not one of its own. Facts the knowledge base already holds are left out, and at most 100 replies a day are read. A question is something a sender asked about the business that neither the conversation nor the knowledge base answers: when the AI suggests replies to an incoming message, it notes up to 3 such questions, at the level of the domain the message arrived at, chosen the same way. Accept a question with its answer and it becomes a note.

The same fact or question again counts up occurrences instead of adding a second suggestion, and one that was dismissed is not suggested again. Both kinds stop while the workspace setting knowledgeLearning is off, which settings.update changes.

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

Saves a pending suggestion or question as a note, marks it accepted and resolves with both: the suggestion, its sourceId naming the new note, and the note itself in item. Any field you send takes the place of the suggested one, so you can tidy the title, rewrite the text, move it to another level or pin it on the way in. The note keeps the conversation the suggestion came from in threadId.

A question needs its answer in body, and its title stays the question unless you send one. Answering a question this way is how it becomes a note the AI uses from then on.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.

Marks a pending suggestion or question dismissed and resolves with it. It leaves the pending list, the same fact or question is not suggested again, and nothing is added to the knowledge base.

Dismissing needs the reach to add a note at the level of the suggestion: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address.

Resolves the open warnings about pairs of knowledge items, newest first. Each item is compared with the closest items at every level when it is indexed, and again whenever it changes. duplicate means the two items say nearly the same thing. conflict means the AI found that two closely related items disagree on a fact, such as a price or a deadline, and detail says how in one sentence. The AI looks for conflicts while the workspace setting knowledgeLearning is on, at most 200 times a day.

Change or delete one of the two items to settle a flag: a changed item is compared again once it is indexed, and the flags of a deleted item go with it. When the two are fine as they are, dismiss the flag with dismissFlag. A flag shows only to a caller who can see both items.

Marks a flag dismissed when the two items are fine as they are, and resolves with it. The same two items are not flagged for the same reason again. To settle a real duplicate or conflict instead, change or delete one of the items.

Dismissing needs the reach to change items at the levels of both items: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address.

Resolves every connector at a level the caller can see, newest first. A connector keeps many web pages from one source in the knowledge base, each page as a link item at the connector's level: a site it crawls, a sitemap, an RSS or Atom feed, or a Zendesk help center. Each one says how many items it keeps, its status, when it last synced and when it syncs next.

Adds a connector at one level and resolves with it, queued. Its first sync starts within a minute, and every page it finds becomes a link item at the connector's level, read in the background like any other link.

site reads the page at url and follows its links to pages on the same host under the same path, leaving out what the site's robots.txt disallows. sitemap reads a sitemap, or a sitemap index and up to 5 of its sitemaps. feed reads an RSS or Atom feed. zendesk reads the published articles of a Zendesk help center from its address, such as https://example.zendesk.com.

It keeps at most --page-limit pages, 25 unless you say, and syncs again every --refresh-days days, 7 unless you say: new pages are added, changed ones are read again and the items of pages that are gone are removed. A page already in the knowledge base as a link at the same level is left to that item. Its items count toward the plan allowance, and a sync stops adding pages once that is reached.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole.

Resolves one connector: its source, its level, how many items it keeps, its status, and when it last synced and syncs next. status is queued until a sync starts, syncing while it reads the source, ready once its pages are items, and failed with a failure when the source could not be read after several tries.

Changes the title of a connector, its level, how often it syncs or the most pages it keeps, and resolves with it as it is now. Give at least one field. Moving it to another level moves its items with it, and they are indexed again there. A new --refresh-days counts from the last sync, and a new --page-limit applies from the next sync.

Changing an item needs reach over every address its level covers: the whole workspace needs every address, a domain needs the whole domain, and an address needs that address. A key or an app limited to particular addresses can change items only at those addresses, or at domains it holds whole. Moving a connector needs that reach at both levels.

Removes a connector with every item it added to the knowledge base, and the AI stops using them at once. There is no undo. Links you added yourself stay, even when the connector found the same pages.

Queues a sync that starts within a minute, whatever the schedule says, clears any failure and resolves with the connector, back at queued. Use it after the source changed, or to try again after a failure. Like a scheduled sync, it adds new pages, reads changed ones again and removes the items of pages that are gone.

The AI reads a conversation and drafts one note of the facts in it that the team will need again, leaving out personal details and what matters only to that conversation. Nothing is saved: the draft comes back with a title, a body in Markdown and a scope it suggests, and you keep it, changed as you like, with createNote and the same --thread-id.

scope suggests the domain the conversation arrived at when the caller may add items there, otherwise the whole workspace or the address itself. Each draft counts as one AI action.