Email Alerts

Read and change the account’s email alert settings, and send a test email. These settings are account-wide: they apply to every check.

All three endpoints need an unrestricted key. A key restricted to checks or folders gets 403, because a recipient added here would receive alerts for checks outside the key’s grant.

Events

The events field takes these values:

Event	Sent when
`website_down`	A check goes down
`website_up`	A check recovers
`website_error`	A check returns an error
`ssl_error`	A certificate is invalid or expired
`ssl_warning`	A certificate is close to expiry
`domain_expiring`	A domain is close to expiry
`domain_expired`	A domain has expired
`domain_renewed`	A domain was renewed

See Alert Events for what each one means. Unknown values are dropped.

Get Email Settings

Required scope: alerts:read


GET /v1/public/alerts/email

200 OK


{
  "data": {
    "enabled": true,
    "recipients": ["ops@example.com", "oncall@example.com"],
    "events": ["website_down", "website_up"],
    "emailFormat": "html",
    "updatedAt": 1736985600000
  }
}

If email alerts were never set up, data is null.

Update Email Settings

Required scope: alerts:write


PATCH /v1/public/alerts/email

Send only the fields you want to change.

Field	Type	Description
`recipients`	string[]	1 to 10 email addresses. Replaces the current list. Duplicates are removed
`events`	string[]	Which events send an email. Replaces the current list
`enabled`	boolean	Switch email alerts on or off
`emailFormat`	string	`html` or `text`

The first call, when no settings exist yet, must include recipients. events then defaults to ["website_down", "website_up"] and enabled to true.

200 OK


{
  "data": {
    "enabled": true,
    "recipients": ["ops@example.com"],
    "events": ["website_down", "website_up", "ssl_warning"],
    "emailFormat": "html"
  }
}

Send a Test Email

Required scope: alerts:write


POST /v1/public/alerts/email/test

Sends a test email to every recipient. No request body.

200 OK


{
  "data": {
    "delivered": ["ops@example.com"],
    "message": "Test alert sent to ops@example.com"
  }
}

If a send fails partway, the response is 502 and delivered lists the addresses that did get the email.

Error Responses

Status	Description
400	Invalid field: `recipients` not an array, more than 10, an invalid address, or empty; no valid `events`; `enabled` not a boolean; `emailFormat` not `html` or `text`; or `recipients` missing on the first call
403	Credential missing the required scope, or the key is restricted to checks or folders
404	No alerts endpoint matches the method and path
412	Test only: no email settings, or no recipients
429	Rate limit exceeded
502	Test only: sending failed
503	Test only: email delivery is not configured on the server

Code Examples

cURL


curl -X PATCH \
  -H "X-Api-Key: ek_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"recipients": ["ops@example.com"], "events": ["website_down", "website_up"]}' \
  "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/alerts/email"
 
curl -X POST \
  -H "X-Api-Key: ek_live_your_key_here" \
  "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/alerts/email/test"

JavaScript


const response = await fetch(
  "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/alerts/email",
  {
    method: "PATCH",
    headers: {
      "X-Api-Key": process.env.EXIT1_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ recipients: ["ops@example.com"] }),
  }
);
console.log(await response.json());

Python


import os, requests
 
response = requests.patch(
    "https://us-central1-exit1-dev.cloudfunctions.net/publicApi/v1/public/alerts/email",
    headers={"X-Api-Key": os.environ["EXIT1_API_KEY"]},
    json={"recipients": ["ops@example.com"], "emailFormat": "text"},
)
response.raise_for_status()
print(response.json())