Fetch one version of a mail trigger
const url = 'https://example.com/v1/mail-triggers/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions/1';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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions/1 \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”TriggerId — the trigger id (a UUID).
The version’s number: 1 for the trigger’s first, one more for each after.
Responses
Section titled “Responses”The version.
One version of a mail trigger: what it was from createdAt until the next. A new mail’s run uses the newest when it starts, and keeps it.
object
Counts from 1, one more for each version.
Who made the change, as audit records name an actor (user:<id>, service_account:<id>, …). Absent on a version the runtime made (first-fire, unversioned-edit, pin).
What made the version: register (the trigger’s first), edit (a change to it), owner (a take-over to another owner), first-fire (the runtime’s, at the first fire of a trigger from before versions, or a mail trigger’s first look at its mailbox), unversioned-edit (the runtime’s, at a fire or a mail trigger’s look at its mailbox, or just before an edit or take-over, when the trigger’s definition isn’t its newest version’s, as when a release from before versions changed it during an upgrade) or pin (the runtime’s, when it fixed a mail trigger to the one connection it could use).
What a mail trigger’s version runs, as whom, and which mailbox it reads at what pace, as its record names them, and never its state (status, next or last fire).
object
Run a flow (with flowVersion).
Run an agent (instead of a flow): at agentVersion, else its live 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.
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
{ "cause": "register", "definition": { "owner": { "kind": "user", "isProjectAccount": true }, "mailbox": { "app": "google", "as": "company" } }}version isn’t a positive integer (bad-input, details.field).
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" }}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" }}No mail trigger with that id (trigger-not-found), or it has no version with that number (trigger-version-not-found).
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" }}See also
GET /v1/mail-triggers/{triggerId}: Fetch a mail triggerPATCH /v1/mail-triggers/{triggerId}: Update a mail triggerPOST /v1/mail-triggers/{triggerId}/pause: Pause a mail triggerPOST /v1/mail-triggers/{triggerId}/resume: Resume a mail trigger- Start runs from new mail
- Error code
bad-input - Error code
database-busy - Error code
trigger-not-found - Error code
trigger-version-not-found - Every error code