Create a Round-Trip Email Monitor

Last modified on May 22, 2024

With AlertSite Management API, you can create round-trip email monitors.

To create a new monitor, send a POST request to /monitors/email-round-trip with a JSON body containing the monitor configuration.

Request URL



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

Authorization: Bearer ACCESS_TOKEN

See Authentication for more information.

The authenticating user must have permissions to create monitors.

Request body

The request body is a JSON object containing the monitor configuration parameters. The required data fields for round-trip email monitors are:

  • billing_plancode

  • name

  • smtp_hostname

  • pop3_hostname

  • email

For the full list and description of available fields, see Email server monitor fields.

Parameters that are not specified in the request body will take the values specified in AlertSite defaults and your account defaults. For example, if you do not specify locations for the monitor, it will use your account's default monitoring locations.

Below is the minimal example of round-trip monitor parameters:

    "billing_plancode": "UBM - A/A",
    "name": "Round-Trip Email Monitor",
    "smtp_hostname": "smtps://",
    "pop3_hostname": "pop3s://",
    "email": "[email protected]"

Response body

On success, the operation returns the ID of the created monitor.

  "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 a 15-minute round-trip email monitor.

cURL (Windows)

curl -X POST
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{\"billing_plancode\":\"UBM - A/A\", \"name\":\"Round-Trip Email Monitor\", \"smtp_hostname\":\"smtps://\", \"pop3_hostname\":\"pop3s://\", \"email\":\"[email protected]\", \"email_username\":\"roundtrip.test\", \"email_password\":\"abc123\", \"interval\":15, \"enabled\":true}'

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 '{"billing_plancode":"UBM - A/A", "name":"Round-Trip Email Monitor", "smtp_hostname":"smtps://", "pop3_hostname":"pop3s://", "email":"[email protected]", "email_username":"roundtrip.test", "email_password":"abc123", "interval":15, "enabled":true}'


import requests # Requests library
import json

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

monitor_params = {
  'billing_plancode': 'UBM - A/A',
  'name': 'Round-Trip Email Monitor',
  'smtp_hostname': 'smtps://',
  'pop3_hostname': 'pop3s://',
  'email': '[email protected]',
  'email_username': 'roundtrip.test',
  'email_password': 'abc123',
  'interval': 15,
  'enabled': True

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

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

See Also

Monitor Operations
Edit a Round-Trip Email Monitor
Delete Monitor

Highlight search results