# Guards API

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](/content/docs/reference/flow-schema.html) 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.