Suppressions are email addresses that can be added to groups to prevent certain types of emails from being delivered to those addresses.

GET

Get all suppressions.

Request

1
GET https://api.sendgrid.com/v3/asm/suppressions HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200
[
  {
    "email":"test@example.com",
    "group_id": 1,
    "group_name": "Weekly News",
    "created_at": 1410986704
  },
  {
    "email":"test1@example.com",
    "group_id": 2,
    "group_name": "Daily News",
    "created_at": 1411493671
  },
  {
    "email":"test2@example.com",
    "group_id": 2,
    "group_name": "Daily News",
    "created_at": 1411493671
  }
]

GET

Retrieve all unsubscribe groups that the given email address has been added to.

URI Parameter Required Requirements Description
email Yes String Email address to search for across all groups.

Request

1
GET https://api.sendgrid.com/v3/asm/suppressions/{email} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
HTTP/1.1 200
{
  "suppressions": [
    {
        "description": "Optional description.",
        "id": 1,
        "is_default": true,
        "name": "Weekly News",
        "suppressed": true
    },
    {
        "description": "Some daily news.",
        "id": 2,
        "is_default": true,
        "name": "Daily News",
        "suppressed": true
    },
    {
        "description": "An old group.",
        "id": 2,
        "is_default": false,
        "name": "Old News",
        "suppressed": false
    }
  ]
}

POST

Add recipient addresses to the suppressions list for a given group.

If the group has been deleted, this request will add the address to the global suppression.

URI Parameter Required Requirements Description
recipient_emails Yes Array of valid email addresses Addresses to add to the suppression group

Request

1
POST https://api.sendgrid.com/v3/asm/groups/:group_id/suppressions HTTP/1.1

Response

1
2
3
4
5
6
7
HTTP/1.1 201
{
  "recipient_emails": [
    "test1@example.com",
    "test2@example.com"
  ]
}

GET

Get suppressed addresses for a given group.

Request

1
GET https://api.sendgrid.com/v3/asm/groups/:group_id/suppressions HTTP/1.1

Response

1
2
3
4
5
HTTP/1.1 200
[
  "test1@example.com",
  "test2@example.com"
]

DELETE

Delete a recipient email from the suppressions list for a group.

Request

1
DELETE https://api.sendgrid.com/v3/asm/groups/:group_id/suppressions/:email_address HTTP/1.1

Response

1
HTTP/1.1 204

POST

Use this endpoint to determine if a given list of emails exists in the given suppression group.

When given a list of email addresses and a group ID, this endpoint will return only the email addresses that have been unsubscribed from the given group.

URI Parameter Required Requirements Description
group_id Yes integer The ID of the group that you would like to search.

Request

1
POST https://api.sendgrid.com/v3/asm/groups/:group_id/suppressions/search HTTP/1.1
Request Body
1
2
3
4
5
6
7
{
  "recipient_emails": [
    "test1@example.com",
    "test2@example.com",
    "test3@example.com"
  ]
}

Response

1
2
3
4
5
6
7
8
HTTP/1.1 200

{
  "recipient_emails":[
    "test1@example.com",
    "test2@example.com"
  ]
}