Add a suppression

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

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

Parameter	Type	Required	Description
email	string	Yes	The address to suppress. Max 254 characters. Stored lower-cased.

Example

curl

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" }'

Node.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:

{
  "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.