Remove suppressions

Remove up to 100 addresses from your team's suppression list in one call, by address or by id.

POST /v1/suppressions/batch/remove

Requires a Full access API key.

Body parameters

Send either emails or ids — not both.

Parameter	Type	Required	Description
emails	string[]	One of the two	The addresses to remove. Between 1 and 100. Each max 254 characters.
ids	string[]	One of the two	The suppression ids to remove. Between 1 and 100.

Give both and the request is rejected with 422:

{
  "message": "The emails field prohibits ids from being present.",
  "code": "validation_error",
  "errors": {
    "emails": ["The emails field prohibits ids from being present."]
  },
  "request_id": "8f2c1e64-1b17-4f8c-9f0e-3b6c1e0f5c31"
}

Example

curl

curl -X POST 'https://api.sendgrail.com/v1/suppressions/batch/remove' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": ["woz@example.com", "jobs@example.com"]
  }'

Node.js

const res = await fetch('https://api.sendgrail.com/v1/suppressions/batch/remove', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    emails: ['woz@example.com', 'jobs@example.com'],
  }),
});

const { data } = await res.json();

Response

One entry per matched suppression, each carrying whether it was actually removed:

{
  "data": [
    { "object": "suppression", "id": "a2f5c1d0-7b3e-4c9a-8f21-6d0e5b4c3a10", "deleted": true },
    { "object": "suppression", "id": "b3e6d2e1-8c4f-4d0b-9032-7e1f6c5d4b21", "deleted": false }
  ]
}

deleted tells you which ones stayed

Unlike removing one, a batch does not fail when it meets a permanent suppression — it reports the outcome per address instead:

• deleted: true — the address was a manual suppression, and it's now removed.
• deleted: false — the address was a permanent bounce or complaint suppression, so it was kept. Nothing was removed for it.

This is more informative than a plain success: from one call you learn exactly which addresses came off the list and which are staying on it for deliverability's sake. See Remove a suppression for why the permanent ones can't be lifted.

Addresses (or ids) that don't match any of your suppressions simply don't appear in data — only matched records are reported.