> ## Documentation Index > Fetch the complete documentation index at: https://docs.mercora.io/llms.txt > Use this file to discover all available pages before exploring further. # Triggers > What starts an automation's run, what each trigger asks you to set, and which values it hands to the steps. The **When** row decides what starts a run. Each automation has one trigger: open the menu under **When** and pick it. ![The When menu listing the triggers](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/trigger-menu.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=a1d4653b4c45ea2934c5649a6861d913) The trigger menu. It lists only the triggers you can use in this workspace. | Trigger | Starts a run when | Values the steps can pick | | - | - | - | | [When a document finishes processing](#when-a-document-finishes-processing) | A document of the chosen types is processed (by default, once it's matched to a trade) | The document, its trade and its extracted fields | | [On a schedule](#on-a-schedule) | A set time comes round: every weekday, day, week or month | None | | [Only when someone runs it](#only-when-someone-runs-it) | Someone clicks **Run now** or asks the Copilot to run it | None | | [When another system calls](#when-another-system-calls) | Your system calls the Mercora API | The fields you say it sends | | [When an email arrives](#when-an-email-arrives) | An email matching your filters reaches the workspace's email inbox | The message, its sender, subject and files | | [When a Teams channel gets a post](#when-a-teams-channel-or-whatsapp-group-gets-a-message) | A post arrives in a channel an admin set to **Automations** | The message, its sender and files | | [When a WhatsApp group gets a message](#when-a-teams-channel-or-whatsapp-group-gets-a-message) | A message arrives in a group an admin set to **Automations** | The message, its sender and files | A trigger's values are what the steps pick "from the document", "from the request" or "from the message". See [Use values from earlier steps](https://docs.mercora.io/workflows/automation-values.md). Document and message triggers only count what arrives after the automation is switched on. Switching to another trigger starts it fresh: the old trigger's settings are not kept. ## When a document finishes processing Runs once for each document of the chosen types that Mercora processes. | Setting | What it does | | - | - | | **Types** | Click **+** and pick one or more document types. With none picked, it reads **Any type** and every document starts a run. | | **Invoice categories** | Shown when **Invoice** is one of the types. Click **+** to pick your workspace's invoice categories, such as freight. With none picked, it reads **Any invoice category**. | | **Wait for a trade match** | On (the default): the run starts once the document is matched to a trade, so the steps can use the trade. Off: the run starts as soon as the document is processed, with or without a trade. | ![The document trigger with Types Invoice, Any invoice category and Wait for a trade match on](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/trigger-document.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=2fa24a9548615f513c65f545a23ef349) Runs for every invoice, once it's matched to a trade. **Values for the steps**, listed under **From the document**: * **The document**: the document that started the run. * **Its trade**: the trade it's matched to. * Every field Mercora extracts from the chosen types. For an invoice: **Invoice number**, **Invoice date**, **Due date**, **Vendor name**, **Billed to**, **Currency**, **Subtotal**, **Tax amount** and more. **Example.** Types **Invoice**, **Wait for a trade match** on. When supplier invoice KSS-INV-26-0288 from Kanchana Siam Sugar is matched to trade VCS-S-2026-0714, a run starts, and its steps can pick "from the document · Invoice number" (KSS-INV-26-0288) and "from the document · Its trade". ## On a schedule Runs at a set time. Fill in the sentence: **Starting** a date, **every** weekday, day, week or month, **at** an hour. The time is in the time zone shown at the end, yours when you set it. ![The schedule trigger: Starting, every weekday, at 07:00, Europe/Zurich](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/trigger-schedule.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=a3ac4958eb8eb9096e6e37ba32ce1966) Every weekday at 07:00, Zurich time, starting 3 November. A scheduled run starts with no values of its own: its steps work from what the automation may read under **Uses**. **Example.** Every weekday at 07:00, one AI step: "List the invoices that went overdue yesterday, with their trade, counterparty and amount." With **Invoices & costs** set to **Read**, each morning's run files its list in the Inbox, or nothing on a day with no overdue invoices. ## Only when someone runs it Runs only when someone starts it: **Run now** on the automation's page, or a request to the Copilot such as "Run the overdue invoices automation". Use it for jobs you start by hand, and while you build an automation you'll later put on a schedule. It hands the steps no values. ## When another system calls Runs when your own system, such as an ERP, calls Mercora's API. 1. Click **Save** once. The automation's address then shows under **When**: `POST /api/v1/agents/{id}/run`. Click **Copy**. 2. Your system calls that address with a workspace API key that has the **Automations** scope. Keys are made under **Settings → Administration → API**; see [API keys](https://docs.mercora.io/admin/api-keys.md). 3. Under **Fields it sends**, type the name of each field your system sends, in lower\_snake\_case (such as `contract_number`), click **Add a field**, and pick its type: **Text**, **Number**, **Yes or no** or **Date**. ![The API trigger with Fields it sends: contract\_number as Text and lots as Number](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/trigger-api.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=6cff523a2192d2b6936b662972825f42) An automation another system calls, with the two fields it sends. Your system sends the fields inside `input`, with its own `external_id` for the request: ```bash theme={"system"} curl -X POST https://{workspace}.mercora.io/api/v1/agents/{id}/run \ -H "Authorization: Bearer mk_your_api_key" \ -H "Content-Type: application/json" \ -d '{"external_id": "erp-hedge-4711", "input": {"contract_number": "VCS-S-2026-0714", "lots": 3}}' ``` Sending the same `external_id` and body again with the same API key returns the run it started instead of starting a second one; after a key change it starts a new run. The same `external_id` with a different body is refused. The steps pick each field "from the request": here **Contract number** and **Lots**. See the [API reference](https://docs.mercora.io/api-reference/introduction.md). ## When an email arrives Runs for each email that reaches the workspace's email inbox and matches the filters. Only a workspace admin can save this trigger. | Filter | Matches | | - | - | | **From** | Type a full address or `@domain` and press Enter. Add as many as you need. Empty: any sender. | | **Subject has any of** | Type a word and press Enter. The subject must contain at least one of them as a whole word. Empty: any subject. | | **Only with a file** | On: only emails with an attachment. | ![The email trigger with From @kanchanasiam.example, Subject has any of invoice, and Only with a file on](https://mintcdn.com/placeholder-f4ffdeec/s6Fb5kGGc4sLUuXY/images/workflows/automations/trigger-email.png?fit=max\&auto=format\&n=s6Fb5kGGc4sLUuXY\&q=85\&s=93b23bf3561cb655bab452a9a00b6577) Runs for emails from the supplier's domain whose subject says invoice and that carry a file. An email goes to one place only: once it matches an automation, it no longer goes to Deal Capture or vessel nominations. With no filter at all, every email comes here. Emails from registered freight carriers always stay with [Freight Rates](https://docs.mercora.io/workflows/freight-rates.md). **Values for the steps**, under **From the message**: **The message** (its text), **Who sent it**, **The sender as a member** (always empty for an email, since an email's sender can't be verified), **Where it arrived**, **The subject**, **When it arrived** and **Its files** (attachments, as documents). ## When a Teams channel or WhatsApp group gets a message Runs for each post in a Teams channel, or each message in a WhatsApp group, that an admin set to **Automations** under **Settings → Integrations** ([Microsoft 365](https://docs.mercora.io/integrations/microsoft-365.md), [WhatsApp](https://docs.mercora.io/integrations/whatsapp.md)). These triggers show in the menu only once such a channel or group exists. * **Channels** or **Groups**: click **+** and pick one or more. * **From** (WhatsApp only): phone numbers written in full, such as `+41 79 123 45 67`. Empty: anyone in the group. * **Text has any of**: words the message must contain, at least one. Empty: any message. The values are those of an email, without **The subject**. Here **The sender as a member** is filled when a teammate sent the message. A message goes to one place only. A Teams channel an admin sets to **Automations** no longer goes to Deal Capture, even when no automation listens to it. WhatsApp groups never go to Deal Capture, and a group used for hedging can't be set to **Automations**. ## Next steps * [Steps](https://docs.mercora.io/workflows/automation-steps.md): what happens after the trigger. * [Use values from earlier steps](https://docs.mercora.io/workflows/automation-values.md): put the trigger's values into your steps. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.