Alerts allow you to specify an email address to receive notifications regarding your email usage or statistics.
  • Usage alerts allow you to set the threshold at which an alert will be sent. For example, if you want to be notified when you've used 90% of your current package's allotted emails, you would set the "percentage" parameter to 90.
  • Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, if you want to receive your stats notifications every day, simply set the "frequency" parameter to "daily". Stats notifications include data such as how many emails you sent each day, in addition to other email events such as bounces, drops, unsubscribes, etc.

For more information about alerts, please visit our User Guide.

Get All Alerts [GET]

Retrieve all alerts.

Request

1
GET https://api.sendgrid.com/v3/alerts 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
27
HTTP/1.1 200
[
  {
    "created_at": 1451498784,
    "email_to": "test@example.com",
    "id": 46,
    "percentage": 90,
    "type": "usage_limit",
    "updated_at": 1451498784
  },
  {
    "created_at": 1451498812,
    "email_to": "test@example.com",
    "frequency": "monthly",
    "id": 47,
    "type": "stats_notification",
    "updated_at": 1451498812
  },
  {
    "created_at": 1451520930,
    "email_to": "test@example.com",
    "frequency": "daily",
    "id": 48,
    "type": "stats_notification",
    "updated_at": 1451520930
  }
]

Create a New Alert [POST]

Create a new alert. You can create the same alert multiple times, but with different email addresses specified in the "email_to" parameter. This is useful if you have multiple users on the same account who would like to receive the same alerts.

Request Attribute Required Requirements Description
type Yes string The type of alert you want to create. Can be either usage_limit or stats_notification. A usage_limit alert allows you to set the threshold at which a usage alert will be sent. A stats_notification alert allows you to set how frequently you would like to receive email statistics reports.
Example: usage_limit
email_to Yes string The email address the alert will be sent to.
Example: test@example.com
percentage No number Required for usage_limit. When this usage threshold is reached, the alert will be sent.
Example: 90
frequency No string Required for stats_notification. How frequently the alert will be sent.
Example: daily

Request

1
POST https://api.sendgrid.com/v3/alerts HTTP/1.1
Request Body
1
2
3
4
5
{
  "type": "stats_notification",
  "email_to": "test@example.com",
  "frequency": "daily"
}

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 201
{
  "created_at": 1451520930,
  "email_to": "test@example.com",
  "frequency": "daily",
  "id": 48,
  "type": "stats_notification",
  "updated_at": 1451520930
}

Get an Alert [GET]

Retrieve a specific alert.

Request

1
GET https://api.sendgrid.com/v3/alerts/{alert_id} HTTP/1.1

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 200
{
  "created_at": 1451520930,
  "email_to": "test@example.com",
  "frequency": "daily",
  "id": 48,
  "type": "stats_notification",
  "updated_at": 1451520930
}

Delete an Alert [DELETE]

Delete an alert.

Request

1
DELETE https://api.sendgrid.com/v3/alerts/{alert_id} HTTP/1.1

Response

1
HTTP/1.1 204

Update an Alert [PATCH]

Update an alert.

Request Attribute Required Requirements Description
email_to No string The new email address you want your alert to be sent to.
Example: test@example.com
frequency No string The new frequency at which to send the stats_notification alert.
Example: monthly
percentage No number The new percentage threshold at which the usage_limit alert will be sent.
Example: 90

Request

1
PATCH https://api.sendgrid.com/v3/alerts/{alert_id} HTTP/1.1
Request Body
1
2
3
{
  "email_to": "test@example.com"
}

Response

1
2
3
4
5
6
7
8
9
HTTP/1.1 200
{
  "created_at": 1451520930,
  "email_to": "test@example.com",
  "frequency": "daily",
  "id": 48,
  "type": "stats_notification",
  "updated_at": 1451522691
}