---
title: "Build a workflow"
description: "Lay out a workflow on the canvas, connect its steps, try it with a sample email, then turn it on and follow every run."
last_updated: "2026-10-21"
lang: "en"
status: "beta"
canonical: "https://matchai.co/docs/guide/workflows/build-a-workflow"
---

# Build a workflow

> Lay out a workflow on the canvas, connect its steps, try it with a sample email, then turn it on and follow every run.

**In closed beta. This feature is open to a small group of professionals while we finish it, so it may change. It is coming to every account.**

Source: https://matchai.co/docs/guide/workflows/build-a-workflow

This page builds the most common workflow: a lead email arrives, **Analyze** reads it, and **Create HubSpot contact** adds the lead to HubSpot.

## Before you start [#before-you-start]

Connect the services your workflow will use, in **Settings → Connectors**:

- **Gmail** or **Outlook (Email)**, for the email trigger. You can test a workflow without it, but you need it to turn the workflow on.
- **HubSpot**, for the HubSpot step. Connect it before you set up that step, because the step lists the fields from your own HubSpot account.

See [Matchai Connectors](https://matchai.co/docs/guide/connectors).

<Callout title="Why it works this way">
A workflow runs on its own, often while you are signed out. It cannot ask you to sign in to Gmail or HubSpot each time an email arrives. A connector is the permission you give once, in Settings, and every workflow uses it. When a step needs a service you have not connected, the step shows a warning and a link to connect it.
</Callout>

## Create the workflow [#create-the-workflow]

<Steps>
<Step>
Choose **Workflows** in the sidebar, then **New workflow**. An empty canvas opens.
</Step>
<Step>
To name it, select an empty spot on the canvas. Under **Workflow settings** on the right, type the name in **Workflow name**.
</Step>
</Steps>

Your changes save as you go. **Saving...**, then **Saved**, shows at the bottom of the canvas.

## Add the trigger [#add-the-trigger]

<Steps>
<Step>
Choose **Add step** at the top of the canvas. A new step appears, and **Add a step** opens on the right.
</Step>
<Step>
Choose **Triggers**, then **When email is received**.
</Step>
<Step>
Under **Email provider**, choose **Gmail** or **Outlook**.
</Step>
<Step>
Narrow it down to the emails you care about. In **From** contains, type a sender or a domain, such as the address your lead inquiries come from, and press Enter. In **Subject** contains, type a word from the subject line and press Enter. You can add several values to each.
</Step>
</Steps>

If you leave both filters empty, the workflow runs on every email you receive, and the step warns you. For exactly how the filters match, see [Triggers and actions](https://matchai.co/docs/guide/workflows/triggers-and-actions).

## Add the actions [#add-the-actions]

<Steps>
<Step>
Choose **Add step** again, then **Matchai Intelligence** and **Analyze**.
</Step>
<Step>
Connect the trigger to it. Drag from the small circle on the right side of the trigger and drop it on the **Analyze** step. A line now joins them.
</Step>
<Step>
Choose **Add step**, then **CRMs**, **HubSpot CRM** and **Create HubSpot contact**.
</Step>
<Step>
Connect **Analyze** to it the same way.
</Step>
<Step>
Under **Fields to fill in HubSpot**, tap each field you want filled in. **Email** is always included, because HubSpot uses it to recognise the contact.
</Step>
<Step>
To add a short summary of the lead to the contact in HubSpot, tick **Attach a note to the contact's activity timeline**.
</Step>
</Steps>

### Change the layout [#change-the-layout]

- **Insert a step between two others.** Hover over the line between them and choose the plus button.
- **Remove a connection.** Hover over the line and choose the bin.
- **Remove a step.** Select it, choose **Delete** at the bottom of the panel, then confirm with **Delete**.
- **Leave a step out for now.** Select it and choose **Enabled** at the bottom of the panel, so it reads **Disabled**. Every step after it must be disabled too.

### What a workflow can look like [#what-a-workflow-can-look-like]

- It has one trigger, and nothing connects into the trigger.
- Its steps form a single line. Each step takes in exactly one step, the one before it.

If the layout breaks one of these rules, the run stops before any step starts and tells you what to change.

## Test it [#test-it]

Test every workflow before you turn it on.

<Steps>
<Step>
Choose **Test** at the top of the canvas. **Test this workflow** opens.
</Step>
<Step>
Under **Sample email**, pick one of the sample emails, or choose **Custom** to write your own **From**, **Subject** and **Body**. A real example of the emails you expect gives the most useful result. Matchai keeps your sample for the next test of this workflow, in this browser.
</Step>
<Step>
Under **Execution mode**, choose one:

- **Preview** runs every step but sends nothing to HubSpot. You see the contact that would be created. You can run it as often as you like.
- **Live** really creates the contact in HubSpot. It needs HubSpot connected.
</Step>
<Step>
Choose **Run preview**. For a live test, choose **Run live test**, read the message, then confirm with **Run live test**.
</Step>
</Steps>

While the test runs, a banner shows **Preview test running** or **Live test running**. Choose **Cancel** to stop it. Each step shows what it found on the canvas as it finishes.

When the test ends, the banner shows:

- **Preview passed**, with the HubSpot contact that would be created.
- **Live test passed**, with **Open in HubSpot** to see the new contact.
- **Preview failed** or **Live test failed**, with what went wrong and what to change.

<Callout type="warn" title="A live test creates a real contact">
A live test adds a real contact to your HubSpot account. Delete it in HubSpot afterwards if you do not want to keep it. Every test, Preview or Live, uses Matchai Energy, because the AI steps run for real.
</Callout>

The **Run** button is for workflows you start by hand. An email workflow waits for an email, so **Run** tells you to use **Test** or to turn the workflow on.

## Turn it on and off [#turn-it-on-and-off]

Choose the power button at the top of the canvas, next to **Test**. Matchai confirms with **Workflow activated**, and your list of workflows shows it as **Active**. From then on, each new email in the connected inbox starts a run.

To turn it off, choose the power button again. Matchai confirms with **Workflow deactivated**, and the workflow shows as **Draft**.

Good to know:

- **The email connector must be connected** before you can turn the workflow on. If it is not, Matchai tells you which one to connect.
- **Emails that arrive while the workflow is off are not picked up later.** A run that was already under way when you turned it off still finishes.
- **You can keep editing a workflow while it is on.** Each new email runs the latest version.
- **After you reconnect Gmail, Outlook or HubSpot** in **Settings → Connectors**, turn the workflow off and on again so it uses the new connection.

## Follow every run [#follow-every-run]

Open the **Runs** tab on the right of the canvas. Each run is listed as **Run #1**, **Run #2** and so on, with when it started, how long it took and how many steps ran. Open a run to see each step, what it produced, or why it stopped. Your tests are listed here too.

Every new email starts a run, including emails that do not match your filter. Those runs stop at the trigger with a message saying the email did not match. That is normal: it is the filter doing its job.

Choose **Refresh** to update the list. **Clear All** deletes the whole run history, once you confirm.

## Delete a workflow [#delete-a-workflow]

On the **Workflows** page, hover over the workflow and choose the bin, then **Delete**. This removes the workflow and its run history, and cannot be undone.

## Sitemap

- [Every page of Matchai Docs](https://matchai.co/docs/sitemap.md)
- [llms.txt](https://matchai.co/docs/llms.txt)