# Guards API

Send-time checkpoints over the API: conditions, the four escalating actions, scopes, and the built-in suppression guard that's always on.

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. |
| `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. |

```
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](https://mimeohq.com/docs/reference/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.

See also: [Guards, for humans](https://mimeohq.com/docs/usage/guards) · [Condition vocabulary](https://mimeohq.com/docs/reference/flow-schema)