# kindgi mail-triggers > Start runs of agents and flows from new mail in a Gmail or Outlook mailbox: create, list, get, update, pause, resume, fires, versions, take-ownership, unregister ## `kindgi mail-triggers` **Synopsis** ```sh signature kindgi mail-triggers ``` Start runs of agents and flows from new mail in a Gmail or Outlook mailbox: create, list, get, update, pause, resume, fires, versions, take-ownership, unregister. **Commands** | Command | Description | | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`kindgi mail-triggers list`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-list) | List mail triggers. | | [`kindgi mail-triggers get`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-get) | Fetch a mail trigger as it is now, or the version given. | | [`kindgi mail-triggers create`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-create) | Start a run of an agent or a flow for each new mail in a mailbox, with the mail as its input. | | [`kindgi mail-triggers update`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-update) | Change a mail trigger: what it runs, its mailbox, folder, pace or label, or the tools its runs may call unattended. | | [`kindgi mail-triggers pause`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-pause) | Pause a mail trigger: it stops looking for new mail. | | [`kindgi mail-triggers resume`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-resume) | Resume a paused mail trigger. | | [`kindgi mail-triggers fires`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-fires) | A mail trigger's mail, newest first: the run each started, why it waits (`thread-busy:`, behind an earlier mail of its thread), or why it was skipped, refused or failed. | | [`kindgi mail-triggers versions`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-versions) | List a mail trigger's versions, newest first: when each was made, by whom, and why. | | [`kindgi mail-triggers take-ownership`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-take-ownership) | Become a mail trigger's owner, so its runs act as you, with your connections, from the next poll (for a trigger whose owner left). | | [`kindgi mail-triggers unregister`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers-unregister) | Remove a mail trigger: it stops looking for new mail. | **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) ### `kindgi mail-triggers list` **Synopsis** ```sh signature kindgi mail-triggers list [--project=] [--status=active|paused] [--limit=] [--cursor=] ``` List mail triggers. **Options** | Option | Default | Description | | ------------------- | ----------------------------- | ---------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | `25` (at most `100`) | The most to return (default 25, at most 100). | | `--project ` | none | Only this project's mail triggers. | | `--status ` | none (both active and paused) | Only `active` or only `paused` mail triggers. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** List the mail triggers in a project. ```sh kindgi mail-triggers list --project= ``` List only the paused ones, as a table, with why each is paused. ```sh kindgi mail-triggers list --status=paused --table ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers get` **Synopsis** ```sh signature kindgi mail-triggers get [] ``` Fetch a mail trigger as it is now, or the version given. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Fetch a mail trigger: what it runs, its mailbox and folder, and its status. ```sh kindgi mail-triggers get ``` Fetch version 2 of a mail trigger: what it ran, and which mailbox it watched. ```sh kindgi mail-triggers get 2 ``` From [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md): ```sh pnpm exec kindgi mail-triggers get ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers create` **Synopsis** ```sh signature kindgi mail-triggers create (--agent= [--agent-version=] | --flow= --flow-version=) --mailbox=google|microsoft [--as=person|company] [--folder=] [--poll=] [--runs-per-hour=] [--label=] [--project=] [--run-as=|project] [--allow-unattended=]… ``` Start a run of an agent or a flow for each new mail in a mailbox, with the mail as its input. Its runs act as you (or, with --run-as, a service account or the project's own), with your connections; in them, every call that changes something, or uses the run's own mailbox, waits for a person's yes. **Options** | Option | Default | Description | | ---------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--agent ` | none | Run this agent (at its pinned version, else the latest). | | `--agent-version ` | none (its pinned version, else the latest) | With --agent: run this exact version. | | `--allow-unattended ` | none (a tool that waits for a person still waits) | A tool, by id, whose calls in this trigger's runs needn't wait for a person's yes (repeatable; only tools its agent or flow calls, no wildcard). In a run a mail started, every call that changes something, or uses the run's own mailbox, waits for one otherwise. Needs `admin` on the trigger's project. The tenant's and the agent's approval rules still apply. Repeatable. | | `--as ` | `person` (your own mailbox) | Whose mailbox: `person`, your own, through your connection (default); or `company`, the company's, through the company's connection, which takes `admin` on the project. | | `--flow ` | none | Run this flow (with --flow-version). | | `--flow-version ` | required with `--flow` | With --flow: the flow version to run. | | `--folder ` | none (the inbox) | The Gmail label id, or the Outlook folder id or well-known name, to watch (default: the inbox). | | `--label ` | none | A short label. | | `--mailbox ` | required | The mailbox's app: `google` (Gmail) or `microsoft` (Outlook). | | `--poll ` | `60` (seconds) | How often to look for new mail, in seconds, 30 to 3600 (default 60). | | `--project ` | the tenant's default project | The trigger's project, by id (default: the tenant's default project). | | `--run-as ` | none (you own the trigger) | On the company's mailbox only: a service account, by id, or `project`: the trigger's owner, so its runs act as that account (not as you). `project` runs it as the project's own account, made the first time. The project's own account runs only what the project's editors can. A named account takes `act_as`, and needs a role that runs what the trigger runs (editor on the target's project). Omit it to own the trigger yourself. | | `--runs-per-hour ` | `60` | The most runs its mail starts in an hour, 1 to 600 (default 60). Past it, a mail is refused, and doesn't run later. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Run an agent for each new mail in your own Gmail inbox. ```sh kindgi mail-triggers create --agent=acme.order-desk --mailbox=google ``` Run a flow for each new mail in a folder of the company's Outlook mailbox, looking every two minutes. ```sh kindgi mail-triggers create --flow=acme.triage --flow-version=1.0.0 --mailbox=microsoft --as=company --folder= --poll=120 ``` From [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md): ```sh pnpm exec kindgi mail-triggers create --agent=acme.support-desk --mailbox=google --label="support inbox" pnpm exec kindgi mail-triggers create --agent=acme.support-desk --mailbox=google --as=company \ ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers update` **Synopsis** ```sh signature kindgi mail-triggers update [--agent= [--agent-version=] | --flow= --flow-version=] [--mailbox=google|microsoft --as=person|company] [--folder=] [--poll=] [--runs-per-hour=] [--label=] [--allow-unattended=|none]… ``` Change a mail trigger: what it runs, its mailbox, folder, pace or label, or the tools its runs may call unattended. A flag left out keeps the trigger's value, and its owner stays. On a person's mailbox, only the trigger's owner points it at another of their mailboxes or folders: a project admin can move it to the company's, or take it over to watch their own. **Options** | Option | Default | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--agent ` | unchanged | Run this agent (at its pinned version, else the latest). | | `--agent-version ` | unchanged | With --agent: run this exact version. | | `--allow-unattended ` | unchanged; a trigger that has a list and moves to another flow, agent or mailbox must name it again, or `none` | A tool, by id, whose calls in this trigger's runs needn't wait for a person's yes (repeatable; only tools its agent or flow calls, no wildcard). In a run a mail started, every call that changes something, or uses the run's own mailbox, waits for one otherwise. Needs `admin` on the trigger's project. The tenant's and the agent's approval rules still apply. Replaces the list; `none` clears it; left out, the list is kept, and a new --agent, --flow or mailbox must name it again (or `none`, which the owner of a person's trigger may give with their own change). Repeatable. | | `--as ` | unchanged (given with `--mailbox`) | Whose mailbox: `person`, your own, through your connection; or `company`, the company's, through the company's connection, which takes `admin` on the project. On update, give --mailbox and --as together. | | `--flow ` | unchanged | Run this flow (with --flow-version). | | `--flow-version ` | unchanged | With --flow: the flow version to run. | | `--folder ` | unchanged | The Gmail label id, or the Outlook folder id or well-known name, to watch: `INBOX` on Gmail or `inbox` on Outlook to watch the inbox again. Left out, it keeps the trigger's folder, unless --mailbox and --as name another mailbox: then that mailbox's inbox. On a person's mailbox, only the trigger's owner changes it. | | `--label ` | unchanged | A new label. | | `--mailbox ` | unchanged (given with `--as`) | The mailbox's app: `google` (Gmail) or `microsoft` (Outlook). On update, give --mailbox and --as together. | | `--poll ` | unchanged | How often to look for new mail, in seconds, 30 to 3600. | | `--runs-per-hour ` | unchanged | The most runs its mail starts in an hour, 1 to 600. Past it, a mail is refused, and doesn't run later. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Look for new mail every five minutes, and start at most 30 runs an hour. ```sh kindgi mail-triggers update --poll=300 --runs-per-hour=30 ``` Watch the inbox again, on a trigger of your own Gmail. ```sh kindgi mail-triggers update --folder=INBOX ``` From [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md): ```sh pnpm exec kindgi mail-triggers update --allow-unattended=acme-shop.order-status ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers pause` **Synopsis** ```sh signature kindgi mail-triggers pause ``` Pause a mail trigger: it stops looking for new mail. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Pause a mail trigger: it stops looking for new mail. ```sh kindgi mail-triggers pause ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers resume` **Synopsis** ```sh signature kindgi mail-triggers resume ``` Resume a paused mail trigger. It starts afresh: mail that came while it was paused doesn't start runs. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Resume a paused mail trigger; mail that came while it was paused doesn't start runs. ```sh kindgi mail-triggers resume ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers fires` **Synopsis** ```sh signature kindgi mail-triggers fires [--limit=] [--cursor=] ``` A mail trigger's mail, newest first: the run each started, why it waits (`thread-busy:`, behind an earlier mail of its thread), or why it was skipped, refused or failed. **Options** | Option | Default | Description | | ------------------ | -------------------- | ---------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | `25` (at most `100`) | The most to return (default 25, at most 100). | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** See the run each new mail started, or why it waits or was skipped, as a table. ```sh kindgi mail-triggers fires --table ``` From [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md): ```sh pnpm exec kindgi mail-triggers fires --table ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers versions` **Synopsis** ```sh signature kindgi mail-triggers versions [--limit=] [--cursor=] ``` List a mail trigger's versions, newest first: when each was made, by whom, and why. `kindgi mail-triggers get ` shows one. **Options** | Option | Default | Description | | ------------------ | -------------------- | ---------------------------------------------------------------- | | `--cursor ` | none | Resume after this cursor, from the previous page's `nextCursor`. | | `--limit ` | `25` (at most `100`) | The most to return (default 25, at most 100). | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** List a mail trigger's versions as a table: when each was made, by whom, and why. ```sh kindgi mail-triggers versions --table ``` From [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md): ```sh pnpm exec kindgi mail-triggers versions --table ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers take-ownership` **Synopsis** ```sh signature kindgi mail-triggers take-ownership [--run-as=|project] ``` Become a mail trigger's owner, so its runs act as you, with your connections, from the next poll (for a trigger whose owner left). On a person's mailbox, the mailbox becomes your own. With --run-as, on the company's mailbox, a service account, or with --run-as=project the project's own account, becomes the owner instead. **Options** | Option | Default | Description | | ------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `--run-as ` | none (you own the trigger) | On the company's mailbox only: a service account, by id, or `project`: the trigger's owner, so its runs act as that account (not as you). `project` runs it as the project's own account, made the first time. The project's own account runs only what the project's editors can. A named account takes `act_as`, and needs a role that runs what the trigger runs (editor on the target's project). Omit it to own the trigger yourself. | Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Take over a trigger whose owner left, so its runs act as you. ```sh kindgi mail-triggers take-ownership ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers) ### `kindgi mail-triggers unregister` **Synopsis** ```sh signature kindgi mail-triggers unregister ``` Remove a mail trigger: it stops looking for new mail. **Options** Every command also takes the [global flags](https://docs.kindgi.com/v0.4.0/reference/cli.md#global-flags). **Examples** Remove a mail trigger: it stops looking for new mail. ```sh kindgi mail-triggers unregister ``` **See also** - [Start runs from new mail](https://docs.kindgi.com/v0.4.0/guides/runs/start-runs-from-new-mail.md) - [`kindgi mail-triggers`](https://docs.kindgi.com/v0.4.0/reference/cli/mail-triggers.md#kindgi-mail-triggers)