List mail triggers
const url = 'https://example.com/v1/mail-triggers?limit=25&status=active';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/v1/mail-triggers?limit=25&status=active' \ --header 'Authorization: Bearer <token>'The tenant’s mail triggers whose project the caller may read; with projectId, that project’s only (which needs read on it).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”1..100. Default 25.
Where the previous page ended: its nextCursor, as it came. A runtime that seals cursors takes one only for the same list, filters and caller, within a day; otherwise 400 bad-input, and the list starts again without it. Absent → first page.
Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.
Filter to triggers at a specific status. Values: active | paused.
Only this project’s mail triggers.
Responses
Section titled “Responses”Page of mail triggers.
object
A mail trigger: each new mail in its mailbox’s folder starts a run of its agent or flow, with the mail as the run’s input, as its owner. In such a run, every call that changes something, or uses the run’s own mailbox, waits for a person’s yes unless the trigger lists it (toolsAllowedUnattended).
object
Run a flow (with flowVersion).
Run an agent (instead of a flow): at agentVersion, else its pinned version.
The trigger’s project: its runs are this project’s.
Who its runs act as, with their connections. A service account owns a shared trigger, on the company’s mailbox: one named with runAsServiceAccountId, or the project’s own (runAsProject, isProjectAccount). A person owns a personal one: every trigger on a person’s mailbox, and one on the company’s mailbox registered without either. No edit moves it; only a take-over (POST …/owner) does.
object
The owner’s name at the time of the response: the person’s display name, or the service account’s name. Absent when it can’t be read (no directory, a removed account) and from a runtime before Kindgi 0.1.6: show the id then.
Set when the owner is the trigger’s project’s own service account (runAsProject): the trigger is shared, and runs as the project. Show it as “This project”. Absent otherwise.
The mailbox a mail trigger reads: its app (google: Gmail; microsoft: Outlook) and whose it is (company: the company’s mailbox, through the company’s connection of that app; person: the trigger owner’s own, through their connection).
object
The Gmail label id, or the Outlook folder id or well-known name, it watches. Absent: the inbox.
How often it looks for new mail, in seconds (default 60).
The most runs its mail starts in an hour (default 60). Past it, a mail’s fire is refused (detail starts over-limit:), and that mail doesn’t run later.
Lifecycle status. Only active triggers fire. Tombstoned rows are excluded from every read path.
Why it isn’t polling as it should: connection-missing (the mailbox’s connection is gone or lapsed; polls go on, and work again once it’s back), owner-refused (its owner was removed or may no longer run the target; polls go on and read nothing until that changes or an admin takes it over), or why the runtime paused it.
The trigger’s newest version (GET …/versions): one more for each change to what it runs, when, as whom or with what. Absent until its first version.
The mailbox’s account at its last poll: the connection’s account id and its label (the address). Absent before its first poll.
object
When it last polled the mailbox and got an answer.
The tools whose calls in this trigger’s runs don’t wait for a person’s yes, though a run a mail started asks for one for every call that changes something or uses its mailbox. Absent: none. Each tool by its id, with no wildcard or pattern, and only tools this trigger’s flow or agent calls. It lifts only that wait: the tenant’s approval rules, the agent’s own rules, the permission check (as the trigger’s owner) and the tool’s own limits all still apply.
Example
{ "data": [ { "owner": { "kind": "user", "isProjectAccount": true }, "mailbox": { "app": "google", "as": "company" }, "status": "active" } ]}Missing / malformed / expired / revoked bearer token.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.
object
object
Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).
Optional, kind-specific.
object
Server-assigned request id; also echoed via X-Request-Id header.
Examplegenerated
{ "error": { "code": "example", "message": "example", "details": {}, "requestId": "example" }}