client.mail_triggers

client.mail_triggers — the mailTriggers operations.

On AsyncKindgi every method is the same, awaited.

client.mail_triggers.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    status: Literal['active', 'paused'] | None = None,
    project_id: str | UUID | None = None,
    timeout: float | None = None,
) -> MailTriggerCollectionPage

Signature

List mail triggers. GET /v1/mail-triggers

The tenant's mail triggers whose project the caller may read; with projectId, that project's only (which needs read on it).

client.mail_triggers.register()

register(
    body: RegisterMailTriggerBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> MailTriggerRecord

Signature

Register a mail trigger. POST /v1/mail-triggers

Each new mail in the mailbox's folder starts a run of the trigger's agent or flow, with the mail as the run's input, as the trigger's owner. A trigger on a person's mailbox (config.mailbox.as: person) reads the caller's own mail through their connection, so the caller owns it: it needs write on the project, and a service account can't own it. One on the company's mailbox (company) reads it through the company's connection and needs admin on the project; runAsServiceAccountId makes it shared, owned by that service account (which needs act_as on it), and runAsProject makes it shared, owned by the project's own account (made the first time, with the editor role on the project). Both need execute on what it runs. A trigger that names no projectId goes in the tenant's Default project. In its runs, every call that changes something, or uses the run's own mailbox, waits for a person's yes, unless toolsAllowedUnattended names it: naming it takes admin on the project, each id must be a tool the target calls, and it's audited (trigger-tools-allowed-unattended-set).

client.mail_triggers.get()

get(trigger_id: str | UUID, /, *, timeout: float | None = None) -> MailTriggerRecord

Signature

Fetch a mail trigger. GET /v1/mail-triggers/{triggerId}

client.mail_triggers.update()

update(
    trigger_id: str | UUID,
    body: PatchMailTriggerBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> MailTriggerRecord

Signature

Update a mail trigger. PATCH /v1/mail-triggers/{triggerId}

Changes what it runs (which needs execute on the new target, and must be the project's to reach), its mailbox (replaced whole), folder, pace or label (null clears it). To watch the inbox again, name it as the folder: INBOX on Gmail, inbox on Outlook. No edit moves the owner: a personal trigger's change is its owner's (who needs write on the project) or a project admin's, a shared one's is a project admin's, and the company's mailbox, before or after, takes a project admin. Only a personal trigger's owner chooses what it reads from a person's mailbox, another of their mailboxes or another folder: anyone else, a project admin included, gets a 403, and may take the trigger over to watch their own. A project admin's other changes to a person's trigger, such as what it runs, its pace or a move to the company's mailbox, keep its owner, so its runs go on acting as that person, and they're audited as trigger-changed-for-owner, naming the trigger's version after each. Since no edit moves the owner, with an authorization store a new target (another flow or agent) must be one the owner can run, a person or a service account, else 409 trigger-owner-cannot-run-target; that's not checked when the caller is the owner, nor for an owner that was unregistered or removed. toolsAllowedUnattended replaces the list ([] clears it; absent keeps it, a new version too), and a new target or mailbox while it lists any must name it again. Naming a list takes admin on the project; a personal trigger's owner may name [] with their own new target or mailbox.

client.mail_triggers.pause()

pause(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> MailTriggerRecord

Signature

Pause a mail trigger. POST /v1/mail-triggers/{triggerId}/pause

A paused trigger doesn't poll. A personal trigger's pause is its owner's or a project admin's; a shared one's needs write on the project.

client.mail_triggers.resume()

resume(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> MailTriggerRecord

Signature

Resume a mail trigger. POST /v1/mail-triggers/{triggerId}/resume

It starts afresh: mail that came while it was paused doesn't start runs. Who may resume it is as for a pause.

client.mail_triggers.unregister()

unregister(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> WebhookTriggerUnregisterResult

Signature

Soft-delete a mail trigger (tombstone). POST /v1/mail-triggers/{triggerId}/unregister

Who may unregister it is as for a pause.

client.mail_triggers.fires()

fires(
    trigger_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> MailFirePage

Signature

A mail trigger's mail. GET /v1/mail-triggers/{triggerId}/fires

Newest first: each mail the trigger found and what came of it (MailFire): the run it started, why it waits (thread-busy:), or why it was skipped, refused or failed.

client.mail_triggers.list_versions()

list_versions(
    trigger_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> MailTriggerVersionPage

Signature

A mail trigger's versions. GET /v1/mail-triggers/{triggerId}/versions

Newest first: each version of the mail trigger, what it was from createdAt on, who made it (createdBy) and why (cause). Registering makes version 1, and each change makes the next (a PATCH that alters it, or a take-over to another owner): a PATCH that changes nothing makes none, nor do pausing, resuming or deleting. A version never changes once made. A new mail's run uses the newest when it starts, and keeps it whatever later edits make (the run's trigger.version). A mail trigger from before versions has none until its next change or its next look at the mailbox. Whoever can read the mail trigger can read its versions.

client.mail_triggers.get_version()

get_version(
    trigger_id: str | UUID,
    version: int,
    /,
    *,
    timeout: float | None = None,
) -> MailTriggerVersion

Signature

Fetch one version of a mail trigger. GET /v1/mail-triggers/{triggerId}/versions/{version}

client.mail_triggers.take_ownership()

take_ownership(
    trigger_id: str | UUID,
    body: TakeTriggerOwnerBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> MailTriggerRecord

Signature

Take over a mail trigger. POST /v1/mail-triggers/{triggerId}/owner

The only way a mail trigger's owner changes. The caller becomes it, so its runs act as the caller, with the caller's connections, from the next poll; on a person's mailbox, the mailbox becomes the caller's own, and the next poll starts afresh. Needs admin on the trigger's project and execute on its target. On the company's mailbox, name runAsServiceAccountId instead to make a service account the owner: that needs act_as on the account, and the account must itself hold what its target needs. With an authorization store, that's checked when the account is named: an account that can't is refused (409 trigger-owner-cannot-run-target). Or name runAsProject: true to make the project's own service account the owner, made the first time with the editor role on the project. It runs only what the project's editors can, and is checked the same way. The trigger keeps its toolsAllowedUnattended; a body naming it is refused (change it with PATCH).