---
title: "List correspondent policy audit events"
method: GET
path: "/v1/policy/audit"
tags: ["policy"]
---

# List correspondent policy audit events

`GET /v1/policy/audit`

## Request

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

Read the append-only audit trail for correspondent policy, newest first. Two kinds of event share one stream: `rule_added`, `rule_removed`, `mode_changed`, and `scope_deleted` record who moved the boundary and how (`scope_deleted` covers a pod or inbox being deleted, which cascade-deletes its policy — the row carries the modes and rules that were removed, so lifting a restriction by deleting its scope is not a silent operation). `send_rejected` and `inbound_rejected` record what the boundary refused: a send the outbound policy would not make, and inbound mail it would not accept. Both are deduped to one row per inbox + correspondent per hour, so neither a looping agent nor an outside sender can flood the trail. Rows are never updated or deleted. Inbox-scoped keys are rejected. A pod-scoped key may read the trail for its own pod or an inbox in that pod (`?podId=` / `?inboxId=`), never the unfiltered account-wide trail.

## Query parameters

- `podId` string
- `inboxId` string
- `action` string
- `direction` 'inbound' | 'outbound'
- `since` string
- `until` string
- `limit` string
- `offset` string

## Response `200`

A page of audit events plus the unpaginated `total`. Each event carries its scope (with the pod name / inbox address resolved at read time, or null if since deleted), the acting console user where there was one, and an action-specific `detail` object: `type`/`valueType`/`value` for rule events, `from`/`to` for mode changes, and `rejectedRecipient`/`reason`/`matchedScope` for rejected sends.

- object: A page of audit events plus the unpaginated `total`. Each event carries its scope (with the pod name / inbox address resolved at read time, or null if since deleted), the acting console user where there was one, and an action-specific `detail` object: `type`/`valueType`/`value` for rule events, `from`/`to` for mode changes, and `rejectedRecipient`/`reason`/`matchedScope` for rejected sends.

## Other responses

- `400`: An unknown `action`, or a `since`/`until` that is not a valid timestamp
- `403`: The authenticating key is scoped and cannot read the audit trail (`forbidden`)
- `404`: Pod or inbox not found

---

[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)