Send Alert

Create an email alert with HTTP POST

Request

HTTP Method

POST

URL

https://api.thingspeak.com/alerts/send

URL Parameters

No available parameters

Headers

The ThingSpeak-Alerts-API-Key and Content-Type headers are required. The Accept header is optional.

Name	Priority	Description	Value Type
ThingSpeak-Alerts-API-Key	Required	Specify the alerts API key, which you can find in your profile. This key is different from the channel API and user API keys.	string
Content-Type	Required	application/json application/x-www-form-urlencoded	string

Body Parameters

Name	Priority	Description	Value Type
subject	Optional	Specify the subject for the email message, up to 60 characters.	string
body	Optional	Specify the body of the email message, up to 500 characters.	string

Response

Success

HTTP Status Code

202 Accepted

Error

You can use the Accept header to control the detail provided with error messages. Provide the Accept header with value application/json,application/problem+json and the server returns detailed error messages along with the standard HTTP response code.

For the full list of possible HTTP errors, see Error Codes.

Examples

Send Email Alert with POSTMAN

Use POSTMAN to make HTTP requests using the RESTful API for ThingSpeak.

Create an alert with a detailed subject and body.

1. Create the POST Request. In POSTMAN, select POST from the list of HTTP verbs, and enter https://api.thingspeak.com/alerts/send in the address bar.

2. Enter the headers. Select the Headers tab. Enter these key and value pairs.

   Key	Value
   Thingspeak-Alerts-API-Key	XXXXXXXXXXXXXXXX
   Content-Type	application/json

   

3. Enter the body information. Select the Body tab, and select raw. Enter this JSON code.

   {
       "subject": "ThingSpeak Alert email",
       "body": "The water level has reached its limit"
   }

The response is in JSON format. The server response value is 202 OK, indicating an accepted request. The email is sent shortly after.

Respond to Channel Data with Alert Using MATLAB

Use MATLAB^® to generate an alert when the mean value in a channel is above a set threshold. This example uses ThingSpeak channel 276330, which contains live office temperature data in field 7. Note that you can write the following code in any MATLAB environment, including MATLAB Analysis and desktop MATLAB.

Set the alerts API key and the URL for the request. Your alerts API key is located at Account > My Profile.

Read data from the channel and calculate the mean value of the data.

data = thingSpeakRead(276330,"NumMinutes", 100);
aveTemp = mean(data(:, 7));

Set the alerts API key and the URL for the request. Your alerts API key is located at Account > My Profile.

apiKey = 'XXXXXXXXXXXXXXXX';
alertURL = "https://api.thingspeak.com/alerts/send";

The alerts send request requires an API key header. Build weboptions so that webwrite can appropriately write your HTTP request. Also create the email body and subject.

Tip

When you create an alert in MATLAB using webwrite, the required Content-Type header is automatically specified.

options = weboptions("HeaderFields", ["ThingSpeak-Alerts-API-Key", apiKey ]);
alertBody = sprintf("The temperature is %0.2f°F.", aveTemp);
alertSubject = sprintf("🌡 Temperature exceeded 60.0°F!");

If the temperature is warmer than 60 °F, send an alert.

if aveTemp > 60.0
    webwrite(alertURL, "body", alertBody, "subject", alertSubject, options);
end    

The time stamp used in the email is in the time zone set in your ThingSpeak Settings, which you can find in Account > My Profile. You can use the Get Alert History API call to track the status of your email.

Now you can use the TimeControl app to schedule this code to run at regular intervals. Go to Apps > TimeControl and select new TimeControl. Set the Frequency to Recurring and Recurrence to 100 minutes. Select the Action as MATLAB analysis and choose the name of the MATLAB analysis you wrote in the previous step. Save the TimeControl.

When the average temperature exceeds 60 ℉, you will receive an email from ThingSpeak.

Limitations

• Users are limited to 2 alerts every 30 minutes. The rate limit is applied when the request is made, not when the email is sent. If you exceed the request limit, the API returns the response code 429.