How can we help?

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.

• Learn more about Cordial API authentication here

Message and automation ID

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

• Learn how to find message and automation IDs here

Methods, parameters, and examples

• POST/v2/alerts
• GET/v2/alerts
• GET/v2/alerts/{id}
• PUT/v2/alerts/{id}
• DELETE/v2/alerts/{id}

POST/v2/alerts

• Parameters
• Example JSON request
• Example request URL
• Example JSON response

* Required

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

• Example request URLs

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}

• Example request URL

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

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

PUT/v2/alerts/{id}

• Parameters and JSON request example
• Example request URL
• Example JSON response

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}

• Example request URL

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

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

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.