Main Content

Send Alert

Create email alert with HTTP POST

expand all in page

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.

NamePriorityDescriptionValue Type
ThingSpeak-Alerts-API-KeyRequired

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-TypeRequired

  • application/json

  • application/x-www-form-urlencoded

string

Body Parameters

NamePriorityDescriptionValue Type
subjectOptional

Specify the subject for the email message, up to 60 characters.

string

bodyOptional

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

expand all

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.

    KeyValue
    Thingspeak-Alerts-API-KeyXXXXXXXXXXXXXXXX
    Content-Typeapplication/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.

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.

See Also

Functions

Topics