Skip to main content

​
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

ReasonHow it’s addedRemovable via API?
hard_bounceAutomatic (permanent delivery failure)❌
soft_bounceAutomatic (after repeated failures)❌
spam_complaintAutomatic (recipient marked as spam)❌
unsubscribeAutomatic (recipient unsubscribed)✅
manualYou added it via the API✅
blocklistAddress 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

ParameterTypeDefaultDescription
limitinteger50Results per page (max 100)
offsetinteger0Number of results to skip
reasonstring—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):
FieldTypeRequiredDescription
emailstring✅Valid email address to suppress
reasonstring✅manual or unsubscribe
notesstring—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.