Skip to content

Add a suppression ​

Add an address to your team's suppression list — SendGrail will not send to it again.

http
POST /v1/suppressions

Requires a Full access API key — a suppression shapes who your account can mail, so a sending key embedded in an app cannot add one.

Body parameters ​

ParameterTypeRequiredDescription
emailstringYesThe address to suppress. Max 254 characters. Stored lower-cased.

Example ​

bash
curl -X POST 'https://api.sendgrail.com/v1/suppressions' \
  -H "Authorization: Bearer $SENDGRAIL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "email": "woz@example.com" }'
js
const res = await fetch('https://api.sendgrail.com/v1/suppressions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SENDGRAIL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ email: 'woz@example.com' }),
});

const suppression = await res.json();

Response ​

201, and the id of the suppression — nothing more:

json
{
  "object": "suppression",
  "id": "a2f5c1d0-7b3e-4c9a-8f21-6d0e5b4c3a10"
}

To read the full object — its origin, and what triggered it — pass this id to Retrieve a suppression.

Adding one is manual, and never downgrades an existing one ​

An address you add by hand is suppressed with origin: "manual", and only a manual suppression can be removed later.

If the address is already suppressed, adding it again is a no-op: you get back the existing suppression's id, and its origin is left alone. In particular, an address that was suppressed automatically for a bounce or a complaint is not downgraded to manual — that would quietly throw away its permanence and let the address be un-suppressed. A bounce stays a bounce.

To suppress many addresses in one call, see Add suppressions.

Suppressions are enforced on every send ​

Once an address is on the list, it stays off the wire. Send an email to a suppressed address and the send is not delivered — the resulting email object reports a suppressed result rather than mailing it. Suppressing an address is how you make that stick account-wide, not just for one send.

Transactional email on your own domain.