> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gork.email/llms.txt
> Use this file to discover all available pages before exploring further.

# Suppressions API

> Manage email suppressions to protect sender reputation from hard bounces and spam complaints.

The Suppressions API protects your domain's sending reputation and delivers on Google and Yahoo compliance requirements. When an email bounces or receives a spam complaint via Feedback Loop (FBL), Gork automatically adds the recipient address to the suppression list, preventing future sends to that destination.

## Google & Yahoo Deliverability Ceilings

Gork strictly enforces deliverability guardrails across all outbound traffic:

* **Spam Complaint Ceiling**: `< 0.30%` (per Google Email Sender Guidelines)
* **Hard Bounce Ceiling**: `< 5.0%`
* Senders that exceed these thresholds trigger an automatic protective circuit breaker, pausing outbound sending (`403 Forbidden` with code `sending_not_approved`) until reviewed in the console.

***

## 1. List Suppressions

Retrieve suppressed email addresses for your organization.

### Endpoint

`GET /v1/suppressions`

### Query Parameters

<ParamField query="reason" type="string">
  Filter by suppression reason: `hard_bounce`, `complaint`, `unsubscribe`, or `manual`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of records to return.
</ParamField>

### Response Example

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "sup_91823746",
      "email": "invalid-recipient@example.com",
      "reason": "hard_bounce",
      "source": "ses_bounce",
      "createdAt": "2026-09-17T12:00:00.000Z"
    },
    {
      "id": "sup_19283746",
      "email": "complaining-user@domain.com",
      "reason": "complaint",
      "source": "feedback_loop",
      "createdAt": "2026-09-17T13:15:00.000Z"
    }
  ]
}
```

***

## 2. Add Suppression

Manually add an email address to the suppression list to immediately block future outgoing messages.

### Endpoint

`POST /v1/suppressions`

### Request Body

<ParamField body="email" type="string" required>
  The recipient email address to suppress.
</ParamField>

<ParamField body="reason" type="string" default="manual">
  Reason for suppression: `manual`, `unsubscribe`, `hard_bounce`, or `complaint`.
</ParamField>

### Request Example

```bash cURL theme={null}
curl -X POST https://api.gork.email/v1/suppressions \
  -H "Authorization: Bearer gork_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "reason": "manual"
  }'
```

```json Response 201 Created theme={null}
{
  "data": {
    "id": "sup_81923019",
    "email": "user@example.com",
    "reason": "manual",
    "source": "api",
    "createdAt": "2026-09-17T14:00:00.000Z"
  }
}
```

***

## 3. Remove Suppression

Remove an address from the suppression list, allowing agents to send to this recipient again.

### Endpoint

`DELETE /v1/suppressions/{id}`

### Path Parameters

<ParamField path="id" type="string" required>
  The unique ID of the suppression record (`sup_...`).
</ParamField>

### Response Example

```json 200 OK theme={null}
{
  "data": {
    "id": "sup_81923019",
    "status": "deleted"
  }
}
```