# Get domain forwarding rate limit usage

Returns outbound email forwarding rate limit consumption (for group expansions and redirects) over the rolling 24-hour window for a domain. For an SRS bounce-return domain the isolated bounce-return budget is reported separately as `srsBounce`.

## `GET /api/v1/domains/{domain}/forward-usage`

### Path parameters

- `domain` (string, required) — Domain name (e.g. 'example.com')

### Responses

**200** — Current forwarding limit usage and effective limits

`application/json` → SendUsage & object

- `burstWindowSeconds` (integer <int64>, required) — Width of one burst bucket in seconds (3600); the burst figures cover two of them
- `messages` (integer <int64>, required) — Number of distinct messages sent in the rolling 24-hour window, plus each accepted list post whose fan-out is still being delivered: the count the daily limit is checked against
- `messagesHour` (integer <int64>, required) — Distinct messages in the BURST window — the current hourly bucket plus the previous one, so a burst stays visible for up to an hour after it ended
- `msgsPerDay` (integer | null, required) — Configured daily message limit (null = unlimited or unenforced)
- `msgsPerHour` (integer | null, required) — Configured hourly (burst) message limit (null = unlimited or unenforced)
- `rcptsPerDay` (integer | null, required) — Configured daily recipient limit (null = unlimited or unenforced)
- `rcptsPerHour` (integer | null, required) — Configured hourly (burst) recipient limit (null = unlimited or unenforced)
- `recipients` (integer <int64>, required) — Total recipient count sent to in the rolling 24-hour window, plus the recipients an accepted list post still holds for its fan-out: the count the daily limit is checked against
- `recipientsHour` (integer <int64>, required) — Recipients in the BURST window (current + previous hourly bucket)
- `sendHold` ("disabled" | "paused" | null, required) — The mailbox's own hold: 'disabled' = permanent stop, 'paused' = reversible hold, null = neither
  - _option 1: "disabled" | "paused"_
  - _option 2: null_
  - _option 3: null_
- `windowSeconds` (integer <int64>, required) — Duration of the rate-limit window in seconds (e.g. 86400 for 24h)
- `srsBounce` (object) — The SRS bounce-return channel's own budget — present only when the domain carries the srs flag. Isolated from the forwarding budget above, because SRS-shaped mail is an unauthenticated trigger and must not be able to spend a tenant channel's allowance.
  - `messages` (integer, required) — Bounce-return relays spent in the rolling 24-hour window
  - `msgsPerDay` (integer | null, required) — Daily bounce-return limit (null = unenforced)

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Domain not found or not accessible to this principal

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/domains/{domain}/forward-usage' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.domains.getForwardUsage`](/docs/sdks/typescript/domains/get-forward-usage)

```ts
const result = await openemail.domains.getForwardUsage(domain)
```
