The Black Friday sale: $100 off Mimeo. Buy now →
Docs menu Guards API

Guards API

This page is written for AI agents. People ask their agent to do the work; see How it fits together.

Send-time checkpoints: a condition about the person, checked at the moment an email is about to go out, and what to do when it's true.

Method & path What it does
GET /api/v1/guards Every guard in evaluation order, what each is holding, plus the condition vocabulary this install knows.
POST /api/v1/guards Create one.
GET /api/v1/guards/:id One guard.
PATCH /api/v1/guards/:id Update it. Saving enabled: false releases its holds.
DELETE /api/v1/guards/:id Delete it, releasing whatever it held.
POST /api/v1/guards/:id/toggle Body: enabled. Turning one off releases its holds straight away.
POST /api/v1/guards
{ "name": "Members skip pitches",
  "action": "skip",
  "scope_kind": "label",
  "scope_value": "pitch",
  "enabled": true,
  "condition": { "type": "has_tag", "tag": "member" } }

Note: action is read from the request body specifically, because action is also Rails' own routing parameter. Send it as JSON and it works as written.

Actions, in escalating order

Action What happens to this send
pause Held, and it waits. Releases by itself when the condition stops being true.
skip Dropped, and the person carries on to whatever comes next.
cancel_sequence Their whole run through that sequence ends.
exit_flow Their run through the flow ends.

Scopes

scope_kind Covers
all Every email. scope_value is ignored and cleared.
label Emails carrying that label.
flow Emails scheduled by that flow (by key).
sequence Emails from that sequence (by id).
broadcast That broadcast's sends (by id).

The built-in suppression guard

Unsubscribed → drop. Always on, not deletable, and toggle refuses it with 422. It's the standing guarantee the entire provider seam rests on: the local database is the suppression authority, checked before every send, whatever the provider does or doesn't do on its side. A guard you can switch off wouldn't be that.

Conditions

The same vocabulary as flow branches and segments — the flow schema lists every type and operator. GET /api/v1/guards returns the install's own fields, tags, products and segments alongside, so a condition can be written without guessing at names.

POST and PATCH check the condition whenever it changes — the same check segments and mimeo push apply — and refuse a bad one with the problem's code, such as condition_within_days_invalid. MCP's save_guard does the same.

See also: Guards, for humans · Condition vocabulary

View as Markdown

Powerful email automation you fully control.

Buy now