---
title: "Replace correspondent policy"
method: PUT
path: "/v1/policy"
tags: ["policy"]
---

# Replace correspondent policy

`PUT /v1/policy`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/policy`
- Auth: HTTP bearer

Declaratively set a scope's entire policy in one call — ideal for automated provisioning. Sets the inbound and/or outbound mode and REPLACES the scope's own rules for any direction you include. Rules created here are fail-closed (an empty allowlist denies all). Omitted directions are left untouched. Inbox-scoped keys are rejected. A pod-scoped key may mutate its own pod or an inbox in that pod, never account-wide policy. Pod keys cannot set `none` or extra allows on a parent allowlist.

## Query parameters

- `podId` string
- `inboxId` string

## Request body

- object
  - `inbound` object: Inbound (who may send to this scope) policy to set. Omit to leave inbound untouched.
    - `mode` 'none' | 'allowlist' | 'inherit': `none` = no filtering; `allowlist` = only listed correspondents are permitted (empty allowlist denies all — fail closed); `inherit` = defer to the parent scope (pod, then account). Not valid at the account scope.
    - `rules` object[]: Replaces this scope's own inbound rules. Omit to leave rules untouched; pass [] to clear them.
      - `type` 'allow' | 'block', required
      - `value` string, required: An email address (`user@example.com`), a whole domain (`example.com`), or a domain and all its subdomains (`*.example.com`, which also covers `example.com` itself).
  - `outbound` object: Outbound (who this scope may send to) policy to set. Omit to leave outbound untouched.
    - `mode` 'none' | 'allowlist' | 'inherit': `none` = no filtering; `allowlist` = only listed correspondents are permitted (empty allowlist denies all — fail closed); `inherit` = defer to the parent scope (pod, then account). Not valid at the account scope.
    - `rules` object[]: Replaces this scope's own outbound rules. Omit to leave rules untouched; pass [] to clear them.
      - `type` 'allow' | 'block', required
      - `value` string, required

## Response `200`

The resulting policy for the scope

- object: The resulting policy for the scope

## Other responses

- `403`: The authenticating key is scoped and cannot manage policy
- `404`: Pod or inbox not found
- `422`: Invalid mode for the scope, or an invalid rule value

---

[API](https://skmtc.dev/openmail/apis/openmail-api.md) · [All operations](https://skmtc.dev/openmail/apis/openmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openmail/apis/openmail-api/revisions/b943eecca7e2?raw)