An introduction to actions

If events are where Mechanic begins, actions are where it concludes, with tasks hanging out in the middle.

A task can run one action every time it runs, or it might run many actions – it all depends on the task.

Mechanic supports different types of actions, which can each be configured to control what actually occurs when the action is run.

Learn more about Mechanic's action types here.

For developers

The language around actions is super specific, and the distinctions are important!


At the risk of getting circular, when we say "action", we refer to the combination of action type and action options. There's no connection to the event: this combination is the result of running a task script against a given event, and is constructed using the action definitions that the task script renders.

When the action runs, we have (naturally) an action run.

Action type

A simple string, indicating what sort of action you wish to execute. "email"  and "shopify"  are super common! 

Action options

Each action type requires a certain set of options. Naturally, for an email action, Mechanic wants to know where to send the email, what subject to use, and what to send in the body of the message. Read about each action type to see what options are required.

Action definition

This is a JSON object that combines the action type with the action options. The task scripts you write in Mechanic are responsible for constructing these definitions.

Tip: Use the {% action %} tag for fast composition. Learn more here.

The structure of an action definition always starts with this:

{<br> "action": {<br> "type": _____,<br> "options": _____<br> }<br>}

Those three keys, arranged like so, are mandatory: they tell Mechanic that you wish to construct an action, of a specific type, with specific options.

Filling in the blanks, here's what a fleshed-out definition for an email might look like:

{<br> "action": {<br> "type": "email",<br> "options": {<br> "to": "<a href="" rel="nofollow noopener noreferrer" target="_blank"></a>",<br> "subject": "Pleased to meet you!",<br> "body": "Would you like a coffee?"<br> }<br> }<br>}

Note: this is just the resulting JSON, for a single action definition! Mechanic's scripts have the flexibility to specify multiple action definitions, using as much or as little Liquid as you care to leverage. The only requirement is that the final, rendered script be a valid series of JSON objects.

In many tasks, you'll see the {% action %} tag used to compose actions. This is a short-hand we use for generating the full JSON object you see above. For example, this action definition is equivalent to the example above:

{% action "email" %}<br> {<br> "to": "<a href="" rel="nofollow noopener noreferrer" target="_blank"></a>",<br> "subject": "Pleased to meet you!",<br> "body": "Would you like a coffee?"<br> }<br>{% endaction %}

Learn more about the {% action %} tag.

Action run

While you won't see this exact term in the Mechanic interface, an "action run" refers to an action definition that's applied to an incoming event. Literally, it represents what Mechanic tried to do, and what happened as a result. You'll see these represented in Mechanic whenever incoming events occur.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.