Create Alert Recipient

Last modified on August 16, 2021

To create a new alert recipient, send a POST request to /recipients, with a JSON body containing the recipient configuration.

This operation supports all recipient types except for PagerDuty.

Request URL



The request must include the Authorization header containing a user’s access token:

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

Request body

The request body is a JSON object containing the recipient configuration (see Recipient Object). The recipient field specifies the target email address, phone number, or another contact for alerts and must match the expected format.

Unless specified otherwise, recipients are created with availability alerts enabled and performance alerts disabled.

  "name": "DevOps mailing list",
  "method_id": 12,
  "recipient": "",
  "username": "",
  "password": "",

  "availability_alert": true,
  "notify_on_clear": true,
  "attach_screen_capture": true,
  "attach_server_response": true,
  "start_threshold": 1,
  "stop_threshold": 10,
  "remote_commands": false

  "performance_alert": true,
  "performance_alert_type": "20",
  "repeat_performance_alerts": true


Create an email recipient that would receive both availability and performance alerts (including “clear” notifications):

  "name": "DevOps",
  "method_id": 12,
  "recipient": "",
  "availability_alert": true,
  "notify_on_clear": true,
  "performance_alert": true

Create a JSON POST recipient for availability alerts only:

  "name": "HTTP POST to server",
  "method_id": 16,
  "recipient": "",
  "username": "",
  "password": "",
  "availability_alert": true,
  "notify_on_clear": true

Response body

On success, the operation returns HTTP status 200 with the ID of the created recipient:

  "id": "123456"

Error responses have a non-200 status code and contain the errors list, such as:

  "errors": [
      "code": 400,
      "message": "invalid_request - User authentication failed."

Try it out

Click here to test this operation in AlertSite’s interactive API console.

Code examples

This code creates an alert recipient for an email address

cURL (Windows)

curl -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d "{\"recipient\": \"\", \"method_id\": 12}"

Note: New lines are added for readability.
The actual command should be one continuous line.

cURL (bash)

curl -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"recipient": "", "method_id": 12}'


# Python 3.5+
import requests  # Requests library
import json

baseUrl = ''
username = ''  # Replace with your AlertSite login email
password = 'pa55w0rd'          # Replace with your AlertSite password

recipient = {
    'name': 'DevOps',
    'method_id': 12,
    'recipient': '',
    'availability_alert': True,
    'notify_on_clear': True,
    'performance_alert': True

# Log in
payload = {'username': username, 'password': password}
r = + '/access-tokens', data=json.dumps(payload), headers={'Content-Type': 'application/json'})
token = r.json()['access_token']

# Create a recipient
headers = {
    'Authorization': 'Bearer ' + token,
    'Content-Type': 'application/json'
r = + '/recipients', data=json.dumps(recipient), headers=headers)
result = r.json()
if r.status_code ==
    recipient_id = result['id']
    print('Successfully created a recipient. ID: {}'.format(recipient_id))
    print('Could not create a recipient. The following error(s) occurred:', *result['errors'], sep='\n')

See Also

Alert Recipient Operations

Highlight search results