claudetools/.claude/skills/mailprotector/references/api.md

# Mailprotector CloudFilter REST API — Reference

Full endpoint catalog and filter tables for the `mailprotector` skill. SKILL.md
stays lean; the detail lives here.

## Connection

| Item | Value |
|---|---|
| Base URL | `https://emailservice.io/api/v1` |
| Override env | `MAILPROTECTOR_API_BASE_URL` |
| Auth | `Authorization: Bearer <api_key>` |
| Key env override | `MAILPROTECTOR_API_KEY` |
| Vault entry | `msp-tools/mailprotector.sops.yaml`, field `credentials.api_key` |

Credential resolution order: `MAILPROTECTOR_API_KEY` env -> vault
`credentials.api_key` (read via `bash <root>/.claude/scripts/vault.sh get-field`).
A clear setup error is raised if neither resolves.

## Scopes

The five entity types that carry `logs`, `messages`, `configuration`,
`users`, `domains`, and `allow_block_rules` sub-resources. Path form is
`/{scope}/{id}/...`:

```
resellers, customers, domains, user_groups, users
```

The CLI validates `scope` against this set.

## Pagination

| Param | Default | Notes |
|---|---|---|
| `page` | 1 | 1-indexed page number |
| `per_page` | 25 | Max **50** on reseller `messages` |

The response includes an `X-Pagination` response header (a JSON document with
the page/total metadata).

## Global list filtering

List endpoints accept `field[op]=value` filters. Operators:

| Op | Meaning |
|---|---|
| `Gt`  | greater than |
| `Geq` | greater than or equal |
| `Lt`  | less than |
| `Leq` | less than or equal |
| `Eq`  | equal |

Example: `created_at[geq]=2026-06-01`.

## Logs / messages filtering

Every `.../logs` and `.../messages` endpoint accepts these params:

| Param | Default | Allowed values |
|---|---|---|
| `sort_direction` | `desc` | `desc`, `asc` |
| `sort_field` | `@timestamp` | `@timestamp`, `prime.direction`, `prime.from_header_raw`, `prime.recipient`, `prime.subject`, `prime.decision`, `prime.score` |
| `page` | 1 | integer |
| `page_size` | (API default) | integer |
| `sender` | (none) | sender filter |
| `recipient` | (none) | recipient filter |
| `subject` | (none) | subject filter |
| `decision` | `all` | `default`, `deliver`, `quarantine_spam`, `quarantine_virus`, `quarantine_policy`, `bounce`, `encrypt`, `delete` |

## READ endpoints

| Method | Path | Client method | CLI |
|---|---|---|---|
| GET | `/domains` | `domains()` | `domains` |
| GET | `/{scope}/{id}/domains` | `domains(scope,id)` | `domains --scope --id` |
| GET | `/domains/{id}` | `domain(id)` | `domain <id>` |
| GET | `/resellers/{id}/customers` | `customers(id)` | `customers <reseller_id>` |
| GET | `/customers/{id}` | `customer(id)` | `customer <id>` |
| GET | `/{scope}/{id}/users` | `users(scope,id)` | `users <scope> <id>` |
| GET | `/users/{id}` | `user(id)` | `user <id>` |
| POST | `/users/find_by_address` | `find_user(address)` | `find-user <address>` |
| GET | `/{scope}/{id}/logs` | `logs(scope,id,...)` | `logs <scope> <id>` |
| GET | `/{scope}/{id}/messages` | `messages(scope,id,...)` | `messages <scope> <id>` |
| GET | `/{scope}/{id}/configuration` | `configuration(scope,id)` | `config <scope> <id>` |
| GET | `/{scope}/{id}/allow_block_rules` | `allow_block_rules(scope,id)` | `rules <scope> <id>` |

**`find_by_address` is a READ** despite being a POST — it looks up a user / alias
by email. It is NOT gated behind `--confirm`.

`status` is a synthetic read: `GET /domains?per_page=1` used purely to validate
the bearer token (HTTP 200 = key good).

## WRITE endpoints (gated behind `--confirm`)

Without `--confirm` the CLI prints `[DRY RUN] Would <action>: <detail>` and exits
with code 2. With `--confirm` it performs the call.

### Release one held message

```
POST /messages/{message_id}/deliver
body: {"include_original_recipients": 1, "recipients": "<optional csv>"}
```
Client: `release_message(message_id, recipients=None)` — CLI: `release <message_id> [--recipients csv] --confirm`

### Bulk release held messages

```
POST /{scope}/{id}/messages/deliver_many
body: {"include_original_recipients": 1, "recipients": "<optional>",
       "all_selected": false, "ids": "<csv ids>"}
```
Client: `release_many(scope, id, ids=None, all_selected=False, recipients=None)`
CLI: `release-many <scope> <id> [--ids csv | --all] [--recipients csv] --confirm`

### Add allow / block rule

```
POST /{scope}/{id}/allow_block_rules
body: {"value": "...", "rule_type": "allow" | "block"}
```
Client: `add_rule(scope, id, value, rule_type)` — CLI: `add-rule <scope> <id> --value <v> --type allow|block --confirm`

### Enable spam release on an entity

```
PUT /{scope}/{id}/configuration
body: {"permissions": {"messages": {"allow_spam_release": true}}}
```
Client: `enable_release(scope, id)` — CLI: `enable-release <scope> <id> --confirm`

This is required before an entity's held **spam** can be released. Check the
state first with `config <scope> <id>` and look at
`permissions.messages.allow_spam_release`.

## Raw escape hatch

```
py mp.py raw <METHOD> <path> [--body JSON] [--confirm]
```
Non-GET methods require `--confirm`. Use for any endpoint not wrapped by a named
command.

## The `allow_spam_release` gotcha

Releasing a held **spam** message will fail (or silently no-op) if the owning
entity does not have `permissions.messages.allow_spam_release = true`. The fix:

1. `py mp.py config <scope> <id>` — confirm `allow_spam_release` is `false`.
2. `py mp.py enable-release <scope> <id> --confirm` — flip it to `true`.
3. Re-run the `release` / `release-many`.

Virus and policy quarantines are governed separately — only spam release is
gated by this permission.