How can we help?

Search

Alerts API

Overview

You can use the alerts API to create, retrieve, update, and delete alerts about message delivery status. This is useful if you want to get alerts when a message delivers above or below the expected rate.

API set name: alerts

Authentication

Cordial's core APIs use HTTPS Basic Authentication (BA). From within the Cordial platform, you can generate an encoded API key for your account and use it for authorization.

Message and automation ID

You need the message ID or message automation ID in order to create delivery alerts via API.

Methods, parameters, and examples

POST/v2/alerts

Method URL path
POST /v2/alerts
  • Creates a new alert using the appropriate JSON body. A successful request will return a unique id for the alert.

  • * Required

    Parameter Type Description Example
    * type string The message delivery metric that will trigger the alert.  total-sent
    * enabled boolean Whether or not the message or automation is currently enabled.  true

    msID

    * Required if mdtID not present.

    		 string Batch message ID. Learn how to find the msID here. 67e1234ab12c48b55a8a5e33

    mdtID

    * Required if msID not present.

    		 string Automation template ID. Learn how to find the mdtID here. 66e3153fa34c48b55a8a5e33
    * notify string Email address where the alert will be sent. email@example.com
    * conditions array Defines the conditions for when the alert will be sent using lt (less than), lte (less than or equal to), gt (greater than), and gte (greater than or equal to) operators. You could set an alert to trigger when total-sent falls below a certain metric.
    * operator string The operator that defines when an alert will be sent: lt (less than), lte (less than or equal to), gt (greater than), and gte (greater than or equal to) lt
    * value number Determines the operator value that will trigger the alert. 10,000
    period number Sets how far back you want the alert to apply. Value is in minutes and must be greater than 15. 180

  • The following will create an alert for the automation with mdtID 66e3153fa34c48b55a8a5e33 when total-sent falls below 500 within a 180-minute time period.

    {
  "type": "total-sent",
  "enabled": true,
  "mdtID": "66e3153fa34c48b55a8a5e33",
  "notify": [
    "email@example.com"
  ],
  "conditions": [
    {
      "operator": "lt",
      "value": 500
    }
  ],
  "period": 180
}

  • The following URL in conjunction with the JSON will perform the POST.

    https://<path>/v2/alerts

  • A successful POST alert request will return a unique alert id. The following alert has an id of 677c262e88aa2fbb590e6ddc

    {
  "success": true,
  "id": "677c262e88aa2fbb590e6ddc"
}

GET/v2/alerts

Method URL Path
GET /v2/alerts
  • Retrieves account alerts in JSON format.

  • You can filter GET alerts requests by message ID (msID), automation ID (mdtID), entity (batch messages or message automations), as well as standard sorting and pagination specifications.

    The following URL will retrieve all of an account's alerts.

    https://<path>/v2/alerts

    The following URL will retrieve alerts for a message automation with an mdtID of 123456.

    https://<path>/v2/alerts?mdtID=123456

    The following URL will retrieve all alerts set for all message-automations in an account using the entity operator.

    https://<path>/v2/alerts?entity=message-automations

    The following URL will retrieve all alerts set for all batch-messages in an account using the entity operator.

    https://<path>/v2/alerts?entity=batch-messages

GET/v2/alerts/{id}

Method URL Path
GET /v2/alerts/{id}
  • Retrieves a specified alert.

  • The following URL will retrieve the alert with the id value of 123456.

    https://<path>/v2/alerts/123456

PUT/v2/alerts/{id}

Method URL path
PUT /v2/alerts/{id}
  • Updates an existing alert using the appropriate JSON body.
  • The alert is defined by its unique id value.

  • Use the alert id along with the same parameters as the POST method above, updating the desired fields.

    The following will update an alert with an id of 123456 with a new notification email (updated-email@example.com) and threshold for total-sent. The updated alert will trigger when the total messages sent is less than (lt) 1,000.

    {
    "id": "123456",
    "type": "total-sent",
    "enabled": yes,
    "notify": [
      "updated-email@example.com"
    ],
    "mdtID": "66e3153fa34c48b55a8a5e33",
    "period": 180,
    "conditions": [
      {
        "operator": "lt",
        "value": 1,000
      }
    ]
  }

  • The following URL in conjunction with the JSON will perform the PUT request.

    https://<path>/v2/alerts/123456

  • Below is an example response for a successful PUT request.

    {
  "success": true,
  "id": "677c262e88aa2fbb590e6ddc"
}

DELETE/v2/alerts/{id}

Method URL path
DELETE /v2/alerts/{id}
  • Deletes an existing alert.
  • The alert is defined by its unique id value.

  • The following URL will delete the contact attribute with the id value of 123456

    https://<path>/v2/alerts/123456

Test in Swagger

You can access and test Cordial's APIs in Swagger.

Error responses

The Cordial API will return an error object with an errorid and message if there is a problem with an API call. Below is a list of errors specific to the Alerts API endpoint, along with suggested modifications to resolve each error. If you receive an error from this API endpoint that is not listed in this table, it's likely recorded on the Global API error responses page.

errorid Message Modifications
VALIDATION_ERROR

Common alert validation errors:

  • Message or message template does not exist.
  • Period must be greater than 15.
  • Make sure you've correctly input the msID or mdtID.
  • Make sure the period specified for the alert is greater than 15 minutes.
ALERT_id_MUST_BE_UNIQUE id must be unique An error will be provided if the id is not unique.
ALERT_id_NOT FOUND The alert id does not exist. Ensure that the id exists and is input correctly.

Comments

0 comments

Please sign in to leave a comment.