Alerts

Run in Postman
Import the SparkPost API as a Postman collection

Alerts can be used to get notifications regarding various activities on your SparkPost account.

Alerts can be configured to send notifications via email to up to 10 email addresses, and supports the following activity:

  • Approaching monthly sending limit

Alerts are configured to be account-wide. Currently, subaccount level alerts are not supported.

Alert Object

Example

{
  "name": "Sparky's Monthly Alert",
  "description": "Example alert that will send a notification when 90% of monthly sending limit is used",
  "id": "cbe0faf0-9051-11e8-ad04-490e82764b23",
  "email_addresses": [
    "sparky@sparkpost.com"
  ],
  "alert_metric": "monthly_sending_limit",
  "threshold": {
    "error": {
      "target": 90,
      "comparator": "gt"
    }
  },
  "enabled": true
}

Attributes

name string

Display name of the alert.

description string

Description of the alert.

id string

Unique alphanumeric id.

email_addresses array

List of email addresses to send alert notifications.

alert_metric enum

Metric that the alert is configured to track.

Possible Values: "monthly_sending_limit"

threshold object

Configuration for level and threshold at which an alert is generated.

enabled boolean

Whether or not the alert is active.

Request

POST /api/labs/alerts
{
  "name": "Sparky's Monthly Alert",
  "description": "Example alert that will send a notification when 90% of monthly sending limit is used",
  "email_addresses": [
    "sparky@sparkpost.com"
  ],
  "alert_metric": "monthly_sending_limit",
  "threshold": {
    "error": {
      "target": 90
    }
  }
}

Response

{
  "results": {
    "id": "cbe0faf0-9051-11e8-ad04-490e82764b23",
    "name": "Sparky's Monthly Alert",
    "enabled": true,
    "alert_metric": "monthly_sending_limit"
  }
}

Create an Alert

POST/api/labs/alerts

Creates a new alert

Request Body

name string required

Display name of the alert.

description string

Description of the alert.

email_addresses array required

List of up to 10 email addresses to send alert notifications

alert_metric enum required

Metric that the alert is configured to track

Possible Values: "monthly_sending_limit"

threshold object required

Configuration for level and threshold at which an alert is generated.

enabled boolean, default is true

Whether or not the alert is active.

Request

GET /api/labs/alerts/cbe0faf0-9051-11e8-ad04-490e82764b23

Response

{
  "name": "Sparky's Monthly Alert",
  "description": "Example alert that will send a notification when 90% of monthly sending limit is used",
  "email_addresses": [
    "sparky@sparkpost.com"
  ],
  "alert_metric": "monthly_sending_limit",
  "threshold": {
    "error": {
      "target": 90,
      "comparator": "gt"
    }
  },
  "enabled": true
}

Retrieve an Alert

GET/api/labs/alerts/{id}

Parameters

id uuid required

Retrieve full information about a single alert.

Request

PUT /api/labs/alerts/cbe0faf0-9051-11e8-ad04-490e82764b23
{
  "name": "Sparky's Updated Monthly Alert",
  "description": "Updated example alert that will send a notification when 80% of monthly sending limit is used",
  "email_addresses": [
    "sparky@sparkpost.com"
  ],
  "threshold": {
    "error": {
      "target": 80
    }
  }
}

Response

{
  "results": {
    "id": "cbe0faf0-9051-11e8-ad04-490e82764b23",
    "name": "Sparky's Updated Monthly Alert",
    "enabled": true,
    "alert_metric": "monthly_sending_limit"
  }
}

Updates an Alert

PUT/api/labs/alerts/{id}

Parameters

id uuid required

Updates an existing alert. Updating email_addresses replaces the the existing array with the new array.

Request Body

name string

Display name of the alert.

description string

Description of the alert.

email_addresses array

List of up to 10 email addresses to send alert notifications.

threshold object

Configuration for level and threshold at which an alert is generated.

enabled boolean

Whether or not the alert is active.

Request

DELETE /api/labs/alerts/cbe0faf0-9051-11e8-ad04-490e82764b23

Response

// Empty response body

Delete an Alert

DELETE/api/labs/alerts/{id}

Parameters

id uuid required

Deletes the alert with the matching id.

Request

GET /api/labs/alerts

Response

{
  "results": [
    {
      "id": "cbe0faf0-9051-11e8-ad04-490e82764b23",
      "name": "Sparky's Monthly Alert",
      "enabled": true,
      "alert_metric": "monthly_sending_limit"
    }
  ]
}

List all Alerts

GET/api/labs/alerts

Returns an array of all your Alerts. Each Alert isn't returned as a full Alert Object, and is abbreviated to the following attributes:

Attributes

name string

Display name of the alert.

id string

Unique alphanumeric id.

enabled boolean

Whether or not the alert is active.

alert_metric enum

Metric that the alert is configured to track.