# Message rules

Messages · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## List automatic messages {#list}

`GET /api/v1/message-rules`

Scopes: `messages:write`. SDK name: `pb.messageRules.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |
| `state` | query | "on" \| "paused" |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/message-rules" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Create an automatic message {#create}

`POST /api/v1/message-rules`

Scopes: `messages:write`. SDK name: `pb.messageRules.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `name` | body | string · max 80 | yes |  |
| `templateIds` | body | string · max 64[] | yes |  |
| `anchor` | body | object \| object | yes |  |
| `offset` | body | object | yes |  |
| · `amount` | body | integer · ≥ 0 · ≤ 366 | yes |  |
| · `unit` | body | "day" \| "hour" | yes |  |
| · `when` | body | "before" \| "after" | yes |  |
| `timeZone` | body | string · max 64 | yes |  |
| `message` | body | string · max 256 | yes |  |
| `match` | body | object \| object \| object[] |  |  |
| `yearly` | body | boolean |  |  |
| `sendAt` | body | string · ^([01]\d\|2[0-3]):[0-5]\d$ |  |  |
| `clearAfter` | body | integer \| null · ≥ 60000 · ≤ 31622400000 |  |  |
| `on` | body | boolean |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/message-rules" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Day-before reminder",
  "templateIds": [
    "0193a1b2-7c00-7000-8000-0000000000b1"
  ],
  "anchor": {
    "kind": "input",
    "input": "startsAt"
  },
  "offset": {
    "amount": 1,
    "unit": "day",
    "when": "before"
  },
  "timeZone": "Europe/Berlin",
  "message": "Tomorrow at 7 PM."
}'
```

## One automatic message {#retrieve}

`GET /api/v1/message-rules/{id}`

Scopes: `messages:write`. SDK name: `pb.messageRules.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Save an automatic message; saving resumes a paused one {#update}

`PUT /api/v1/message-rules/{id}`

Scopes: `messages:write`. SDK name: `pb.messageRules.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `orgId` | body | string · max 64 | yes |  |
| `name` | body | string · max 80 | yes |  |
| `templateIds` | body | string · max 64[] | yes |  |
| `anchor` | body | object \| object | yes |  |
| `offset` | body | object | yes |  |
| · `amount` | body | integer · ≥ 0 · ≤ 366 | yes |  |
| · `unit` | body | "day" \| "hour" | yes |  |
| · `when` | body | "before" \| "after" | yes |  |
| `timeZone` | body | string · max 64 | yes |  |
| `message` | body | string · max 256 | yes |  |
| `version` | body | integer | yes |  |
| `match` | body | object \| object \| object[] |  |  |
| `yearly` | body | boolean |  |  |
| `sendAt` | body | string · ^([01]\d\|2[0-3]):[0-5]\d$ |  |  |
| `clearAfter` | body | integer \| null · ≥ 60000 · ≤ 31622400000 |  |  |
| `on` | body | boolean |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X PUT "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Example",
  "templateIds": [
    "0193a1b2-7c00-7000-8000-0000000000b1"
  ],
  "anchor": {
    "kind": "input",
    "input": "Example"
  },
  "offset": {
    "amount": 0,
    "unit": "day",
    "when": "before"
  },
  "timeZone": "Europe/Berlin",
  "message": "Example",
  "version": 1
}'
```

## Delete an automatic message and cancel its runs that have not started {#delete}

`DELETE /api/v1/message-rules/{id}`

Scopes: `messages:write`. SDK name: `pb.messageRules.delete`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Pause an automatic message {#pause}

`POST /api/v1/message-rules/{id}/pause`

Scopes: `messages:write`. SDK name: `pb.messageRules.pause`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1/pause" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

## Count the passes due each of the next 14 days {#countDue}

`POST /api/v1/message-rules/preview`

Scopes: `messages:write`. SDK name: `pb.messageRules.countDue`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `name` | body | string · max 80 | yes |  |
| `templateIds` | body | string · max 64[] | yes |  |
| `anchor` | body | object \| object | yes |  |
| `offset` | body | object | yes |  |
| · `amount` | body | integer · ≥ 0 · ≤ 366 | yes |  |
| · `unit` | body | "day" \| "hour" | yes |  |
| · `when` | body | "before" \| "after" | yes |  |
| `timeZone` | body | string · max 64 | yes |  |
| `message` | body | string · max 256 | yes |  |
| `match` | body | object \| object \| object[] |  |  |
| `yearly` | body | boolean |  |  |
| `sendAt` | body | string · ^([01]\d\|2[0-3]):[0-5]\d$ |  |  |
| `clearAfter` | body | integer \| null · ≥ 60000 · ≤ 31622400000 |  |  |
| `on` | body | boolean |  |  |
| `ruleId` | body | string · max 64 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/message-rules/preview" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "name": "Example",
  "templateIds": [
    "0193a1b2-7c00-7000-8000-0000000000b1"
  ],
  "anchor": {
    "kind": "input",
    "input": "Example"
  },
  "offset": {
    "amount": 0,
    "unit": "day",
    "when": "before"
  },
  "timeZone": "Europe/Berlin",
  "message": "Example"
}'
```

## Send the text now to one pass {#sendTest}

`POST /api/v1/message-rules/{id}/test`

Scopes: `messages:write`. SDK name: `pb.messageRules.sendTest`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `passId` | body | string · max 64 | yes |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X POST "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1/test" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "passId": "0193a1b2-7c00-7000-8000-0000000000c1"
}'
```

## The messages an automatic message sent {#runs-list}

`GET /api/v1/message-rules/{id}/runs`

Scopes: `messages:write`. SDK name: `pb.messageRules.runs.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MESSAGING_UNSUPPORTED` |  | Use a template that defines a message field, or add one to it. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_NOT_FOUND` |  | Check the id with GET /api/v1/passes and the key's mode. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `RULE_HOURS_NEED_DATETIME` |  | Use a date-and-time input for the rule, or remove the hours. |
| `RULE_INPUT_MISMATCH` |  | Pick templates where the input has the same type. |
| `RULE_INPUT_MISSING` |  | Use an input name from GET /api/v1/templates/{id}/input-schema for every template. |
| `RULE_LIMIT` |  | Pause one with POST /api/v1/message-rules/{id}/pause, then turn this one on. |
| `RULE_NOT_FOUND` |  | Check the id with GET /api/v1/message-rules. |
| `RULE_VERSION` |  | Fetch it with GET /api/v1/message-rules/{id} and send your change again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `VALIDATION` |  | Fix each field in issues and resend. |

```sh
curl -X GET "https://passbook.mobile/api/v1/message-rules/0193a1b2-7c00-7000-8000-0000000000e1/runs" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```
