---
title: List send refusals
openapi: /openapi/mailfully.yaml GET /v1/refusals
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

`GET https://api.mailfully.com/v1/refusals`

List the sends a quota or review ceiling refused at accept time, newest first. Every `429` on a send route leaves a row here — the reason, how many messages and how many recipients the refused request carried — so you can reconcile a gap in your own send log without replaying the request. Refusals carry counts and a reason only; there is no message content to return, because a refused send is never persisted.
Scoped to the calling key's `test`/`live` environment. Not paginated: the response is the most recent `limit` rows. Requires the `send` or `read:emails` scope.

## Authentication

- `apiKey` — http bearer

## Query parameters

- `limit` (integer) — Rows to return, 1–200.

## Response 200

The most recent refusals.
  - response (object)
    - `data` (array, required)
      - `items` (object) — One refused send request. Counts and a reason only — a refused send is never persisted, so there is no content to return.
        - `object` (string, required, one of: send_refusal)
        - `id` (string, required) — The refusal id (a bare ULID, no prefix).
        - `reason` (string, required, one of: daily_quota_exceeded, account_under_review, monthly_quota_exceeded, spend_cap_exceeded, marketing_quota_exceeded) — The `error.type` the request was refused with. `rate_limit_exceeded` never appears here: the per-second limiter refuses before the accept gates run, so it leaves no row.
        - `messages` (integer, required) — Email objects in the refused request — 1 for a single send, N for a batch.
        - `recipients` (integer, required) — Recipients across `to`/`cc`/`bcc` of every object in the refused request. This is the figure the quota was measured against.
        - `created_at` (string, date-time, required)

## Response 401

Authentication failed.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 403

The credential is valid but not permitted.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 422

The request failed validation.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.

## Response 500

An unexpected error occurred.
  - response (object)
    - `error` (object, required)
      - `type` (string, required) — Machine-readable error code.
      - `message` (string, required) — Human-readable error message.
      - `param` (string) — The offending field; present only on validation errors.


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://mailfully.com/docs/api-specs.zip