Suppressions

How suppressions work

When a recipient’s mail server permanently rejects an email (hard bounce) or the recipient marks your email as spam, their address is automatically added to your suppression list. Future sends to suppressed addresses are automatically skipped — the API returns 422 recipient_suppressed instead of queueing the email. This protects your sender reputation and ensures compliance.

Suppression reasons

Reason	How it’s added	Removable via API?
`hard_bounce`	Automatic (permanent delivery failure)	❌
`soft_bounce`	Automatic (after repeated failures)	❌
`spam_complaint`	Automatic (recipient marked as spam)	❌
`unsubscribe`	Automatic (recipient unsubscribed)	✅
`manual`	You added it via the API	✅
`blocklist`	Address is on a known blocklist	❌

Only manual and unsubscribe suppressions can be removed via the API. Bounce and complaint suppressions are permanent to protect your reputation.

List suppressions

curl "https://api.mail.gorillaa.one/v1/suppressions?limit=50&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Parameter	Type	Default	Description
`limit`	`integer`	`50`	Results per page (max 100)
`offset`	`integer`	`0`	Number of results to skip
`reason`	`string`	—	Filter by reason: `hard_bounce`, `spam_complaint`, `unsubscribe`, `manual`, `blocklist`

Response

{
  "data": [
    {
      "id": "sup_abc123",
      "email": "[email protected]",
      "reason": "hard_bounce",
      "source": "automatic",
      "notes": null,
      "suppressedAt": "2026-02-08T14:30:00Z",
      "expiresAt": null
    },
    {
      "id": "sup_def456",
      "email": "[email protected]",
      "reason": "spam_complaint",
      "source": "automatic",
      "notes": null,
      "suppressedAt": "2026-02-07T09:15:00Z",
      "expiresAt": null
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Check if an address is suppressed

Check a specific email address before sending:

curl "https://api.mail.gorillaa.one/v1/suppressions/[email protected]" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (suppressed)

{
  "data": {
    "email": "[email protected]",
    "suppressed": true,
    "reason": "hard_bounce"
  }
}

Response (not suppressed)

{
  "data": {
    "email": "[email protected]",
    "suppressed": false
  }
}

Add a manual suppression

Manually suppress an address (e.g. a customer requests to stop receiving emails):

Field	Type	Required	Description
`email`	`string`	✅	Valid email address to suppress
`reason`	`string`	✅	`manual` or `unsubscribe`
`notes`	`string`	—	Optional notes (max 500 chars)

curl -X POST https://api.mail.gorillaa.one/v1/suppressions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "reason": "manual",
    "notes": "Customer requested opt-out via support ticket #1234"
  }'

Response — `201 Created`

{
  "data": {
    "id": "sup_ghi789",
    "email": "[email protected]",
    "reason": "manual",
    "source": "api",
    "notes": "Customer requested opt-out via support ticket #1234",
    "suppressedAt": "2026-02-09T12:00:00Z"
  }
}

Remove a suppression

Remove a manual or unsubscribe suppression by email address:

curl -X DELETE https://api.mail.gorillaa.one/v1/suppressions/optout%40example.com \
  -H "Authorization: Bearer YOUR_API_KEY"

The email address in the URL must be URL-encoded (e.g. @ becomes %40).

Response — `200 OK`

{
  "data": {
    "email": "[email protected]",
    "removed": true
  }
}

You cannot remove hard_bounce, soft_bounce, spam_complaint, or blocklist suppressions. Attempting to do so returns 422.

Get Started

Guides

Reference

How suppressions work

Suppression reasons

List suppressions

Query parameters

Response

Check if an address is suppressed

Response (suppressed)

Response (not suppressed)

Add a manual suppression

Response — `201 Created`

Remove a suppression

Response — `200 OK`

​How suppressions work

​Suppression reasons

​List suppressions

​Query parameters

​Response

​Check if an address is suppressed

​Response (suppressed)

​Response (not suppressed)

​Add a manual suppression

​Response — 201 Created

​Remove a suppression

​Response — 200 OK

How suppressions work

Suppression reasons

List suppressions

Query parameters

Response

Check if an address is suppressed

Response (suppressed)

Response (not suppressed)

Add a manual suppression

Response — `201 Created`

Remove a suppression

Response — `200 OK`