# Inspect receiving rules

GET /v1/inboxes/{inbox_id}/receiving-policy

Source: https://cherami.to/docs/api/inboxes/get-receiving-policy



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`GET /v1/inboxes/{inbox_id}/receiving-policy`

Requires a [Claim-issued API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

`GET /v1/inboxes/{inbox_id}/receiving-policy` returns `200`.

`enabled: false` pauses blocking without clearing either saved list. When enabled, any supported parsed From address matching an exact address **or** exact domain rejects the incoming mail. Empty lists block nothing. Local-part case matters; domain case does not. Plus tags and dots stay distinct. Each list has at most 100 normalized, unique entries. Domains are lowercase ASCII, including punycode, with no implicit subdomain matching.

`revision` is the saved version, starting at `0` for an unconfigured inbox. Missing, deleted and other-account inboxes return `404`. Inspection is read-only and cannot promise the policy for a later receipt.

Only the human’s browser session can edit rules in [Account → Receiving rules](https://cherami.to/account/receiving-rules), not an API key or OAuth mail grant. See [receiving rules](https://cherami.to/docs/guides/receiving-rules) for parsing boundaries and rejection behavior. From is sender-controlled, not authenticated identity; existing messages are never hidden or deleted by a policy change.

## Parameters [#parameters]

| Parameter  | Location | Required | Type   | Meaning                                        |
| ---------- | -------- | -------- | ------ | ---------------------------------------------- |
| `inbox_id` | path     | Yes      | string | Owned Cherami resource ID returned by the API. |

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/receiving-policy" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Policy](#schema-policy)

```json
{
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "enabled": true,
  "addresses": [],
  "domains": [],
  "revision": 0
}
```

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-500]

`internal_error`: Operation failed; a write may already have happened. Follow the operation-specific recovery below.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: Policy [#schema-policy]

| Field       | Required | Type            | Meaning and constraints                                                                     |
| ----------- | -------- | --------------- | ------------------------------------------------------------------------------------------- |
| `inbox_id`  | Yes      | string          | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value.              |
| `enabled`   | Yes      | boolean         |                                                                                             |
| `addresses` | Yes      | array of string | `maxItems`: `100`                                                                           |
| `domains`   | Yes      | array of string | `maxItems`: `100`                                                                           |
| `revision`  | Yes      | integer         | Zero when unconfigured. Inspection does not reserve a policy for later mail. `minimum`: `0` |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)