Groups are specific types of email you would like your recipients to be able to unsubscribe from or subscribe to. For example: Daily Newsletters, Invoices, System Alerts.

The name and description of the Group will be visible by recipients when they are managing their subscriptions.

POST

Create a new suppression group.

There is a limit of 25 groups per user.

URI Parameter Required Requirements Description
name Yes String. May not share its name with any other suppression group on the user. Max 30 characters The name of the new suppression group
description Yes String. Max 100 characters A description of the suppression group
is_default No Boolean Default value is false

Request

1
POST https://api.sendgrid.com/v3/asm/groups HTTP/1.1
Request Body
1
2
3
4
5
{
  "name": "Product Suggestions",
  "description": "Suggestions for products our users might like.",
  "is_default": true
}

Response

1
2
3
4
5
6
7
8
HTTP/1.1 201 OK

{
  "id":103,
  "name": "Product Suggestions",
  "description": "Suggestions for products our users might like.",
  "is_default": false
}

GET

Retrieve all suppression groups associated with the user.

Request

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[
  {
    "id": 100,
    "name": "Newsletters",
    "description": "Our monthly newsletter.",
    "last_email_sent_at": null,
    "is_default": true,
    "unsubscribes": 400
  },
  {
    "id": 101,
    "name": "Alerts",
    "description 2": "Emails triggered by user-defined rules.",
    "last_email_sent_at": null,
    "is_default": false,
    "unsubscribes": 1
  }
]

GET

Get information on a single suppression group.

Request

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

Response

1
2
3
4
5
6
7
8
{
    "id": 100,
    "name": "Newsletters",
    "description": "Our monthly newsletter.",
    "last_email_sent_at": null,
    "is_default": true,
    "unsubscribes": 400
}

PATCH

Update a suppression group.

URI Parameter Required Requirements Description
name No String. May not share its name with any other suppression group on the user. Max 30 characters The name of the new suppression group
description No String. Max 100 characters A description of the suppression group

Request

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

Response

1
2
3
4
5
6
7
HTTP/1.1 201 OK

{
  "id":103,
  "name": "Item Suggestions",
  "description": "Suggestions for items our users might like."
}

GET

Retrieve information about multiple suppression groups.

This endpoint will return information for each group ID that you include in your request. To add a group ID to your request, simply append &id= followed by the group ID.

URI Parameter Required Requirements Description
id No Integer ID for a suppression group that you want to retrieve information for.

Request

1
GET https://api.sendgrid.com/v3/asm/groups?id={id1}&id={id2} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
HTTP/1.1 200 OK

[
  {
    "id": 100,
    "name": "Newsletters",
    "description": "Our monthly newsletter.",
    "last_email_sent_at": null,
    "is_default" : true,
    "unsubscribes": 400
  },
  {
    "id": 101,
    "name": "Alerts",
    "description 2": "Emails triggered by user-defined rules.",
    "last_email_sent_at": null,
    "is_default" : false,
    "unsubscribes": 1
  }
]

DELETE

Delete a suppression group.

You can only delete groups that have not been attached to sent mail in the last 60 days. If a recipient uses the “one-click unsubscribe” option on an email associated with a deleted group, that recipient will be added to the global suppression list.

Request

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

Response

1
HTTP/1.1 204 NO CONTENT (OK)

Response

1
2
3
4
5
HTTP/1.1 400

{
  "error":"refusing to delete active group: group has been sent to within the past 60 days"
}