EmailAlertChannel Construct

Learn how to configure email alert channels with the Checkly CLI.

Learn more about Email alerts in the email alert documentation.

Use Email Alert Channels to send email notifications when checks fail or recover.

Basic Example

import { EmailAlertChannel } from "checkly/constructs"

const emailChannel = new EmailAlertChannel("email-channel-1", {
  address: "[e-mail]",
})

import { EmailAlertChannel } from "checkly/constructs"

const emailChannel = new EmailAlertChannel("ops-email-channel", {
  address: "[e-mail]",
  sendRecovery: true,
  sendFailure: true,
  sendDegraded: true,
  sslExpiry: true,
  sslExpiryThreshold: 30,
})

Configuration

Email Alert Channel

Configure Email-specific settings:

Parameter	Type	Required	Default	Description
address	string	✅	-	Email address to send notifications to

General Alert Channel

Configure common alert channel properties:

Property	Type	Required	Default	Description
sendRecovery	boolean	❌	true	Send notifications when checks recover
sendFailure	boolean	❌	true	Send notifications when checks fail
sendDegrade	boolean	❌	false	Send notifications when checks degrade (API checks only)
sslExpiry	boolean	❌	false	Send notifications for SSL certificate expiry
sslExpiryThreshold	number	❌	30	Days before SSL expiry to send notification

Email Alert Channel Options

address · string · required

Email address to send notifications to. Each EmailAlertChannel supports only one email address.

Usage:

new EmailAlertChannel('team-email', {
  address: '[e-mail]'
})

Examples:

Team Notifications

const teamEmail = new EmailAlertChannel("team-email", {
  address: "[e-mail]",
})

new ApiCheck("api-health-check", {
  name: "API Health Check",
  alertChannels: [teamEmail],
  request: {
    method: "GET",
    url: "https://api.acme.com/health",
  },
})

const developerEmail = new EmailAlertChannel("developer-email", {
  address: "[e-mail]",
})

new ApiCheck("personal-project-check", {
  name: "Personal Project Check",
  alertChannels: [developerEmail],
  request: {
    method: "GET",
    url: "https://johnspersonalapi.com/status",
  },
})

Use cases: Team notifications, individual alerts, distribution lists, role-based alerting.

General Alert Channel Options

sendRecovery · boolean

Whether to send notifications when checks recover from failure or degraded state.

Usage:

new EmailAlertChannel("recovery-email", {
  address: "[e-mail]",
  sendRecovery: true, // Send recovery notifications
})

Examples:

Recovery Notifications

const opsEmail = new EmailAlertChannel("ops-email", {
  address: "[e-mail]",
  sendRecovery: true, // Get notified when issues are resolved
  sendFailure: true,
})

const alertsEmail = new EmailAlertChannel("alerts-only", {
  address: "[e-mail]",
  sendRecovery: false, // Only failures, no recovery notifications
  sendFailure: true,
})

Use cases: Recovery confirmation, operational awareness, noise reduction.

sendFailure · boolean

Whether to send notifications when checks fail.

Usage:

new EmailAlertChannel("failure-email", {
  address: "[e-mail]",
  sendFailure: true, // Send failure notifications
})

Examples:

Failures Only

const criticalEmail = new EmailAlertChannel("critical-email", {
  address: "[e-mail]",
  sendFailure: true,
  sendRecovery: false,
  sendDegraded: false,
})

const comprehensiveEmail = new EmailAlertChannel("all-notifications", {
  address: "[e-mail]",
  sendFailure: true,
  sendRecovery: true,
  sendDegraded: true,
})

Use cases: Incident response, failure monitoring, operational alerting.

sendDegraded · boolean

Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed).

Usage:

new EmailAlertChannel("performance-email", {
  address: "[e-mail]",
  sendDegraded: true, // Send degraded performance notifications
})

Use cases: Performance monitoring, early warning systems, SLA tracking.

sslExpiry · boolean

Whether to send notifications for SSL certificate expiry warnings.

Usage:

new EmailAlertChannel("security-email", {
  address: "[e-mail]",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Use cases: Certificate management, security compliance, proactive maintenance.

sslExpiryThreshold · number

Number of days before SSL certificate expiry to send notifications. Only relevant when sslExpiry is enabled.

Usage:

new EmailAlertChannel("ssl-monitoring", {
  address: "[e-mail]",
  sslExpiry: true,
  sslExpiryThreshold: 30, // Alert 30 days before expiry
})

Use cases: Certificate renewal planning, compliance management, operational scheduling.

Examples

Multiple Recipients

// Create separate channels for different recipients
const devEmail = new EmailAlertChannel("dev-email", {
  address: "[e-mail]",
  sendDegraded: true,
})

const opsEmail = new EmailAlertChannel("ops-email", {
  address: "[e-mail]",
  sendFailure: true,
  sendRecovery: true,
})

const managerEmail = new EmailAlertChannel("manager-email", {
  address: "[e-mail]",
  sendFailure: true,
  sendRecovery: false,
})

new ApiCheck("important-service", {
  name: "Important Service Check",
  alertChannels: [devEmail, opsEmail, managerEmail],
  request: {
    method: "GET",
    url: "https://api.acme.com/important",
  },
})

// Full configuration example
const comprehensiveEmail = new EmailAlertChannel("comprehensive-alerts", {
  address: "[e-mail]",
  sendRecovery: true, // Know when issues are resolved
  sendFailure: true, // Critical for incident response
  sendDegraded: true, // Early warning for performance issues
  sslExpiry: true, // Certificate management
  sslExpiryThreshold: 30, // One month notice
})

new ApiCheck("comprehensive-monitoring", {
  name: "Comprehensive API Monitoring",
  maxResponseTime: 10000,
  degradedResponseTime: 5000,
  alertChannels: [comprehensiveEmail],
  request: {
    method: "GET",
    url: "https://api.acme.com/comprehensive",
  },
})

Single Email Address: EmailAlertChannel only accepts one email address. For multiple recipients, create separate EmailAlertChannel instances or use distribution lists.

Email Delivery: Email notifications may be subject to spam filters or delivery delays. For critical alerts, consider combining email with other notification methods like SMS or Slack.

Reference an alert channel by ID

If your Checkly account includes alert channels that are not controlled via Checkly constructs, find the email channel ID in the Checkly web UI or via the API and set it using EmailAlertChannel.fromId().

Web UI

1. Go to Alert Channels in your Checkly dashboard
2. Find your email channel and note the ID in the URL or channel details

API

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "X-Checkly-Account: YOUR_ACCOUNT_ID" \
     https://api.checklyhq.com/v1/alert-channels/

Using Existing Channel

// Reference an existing email channel by ID
const existingEmailChannel = EmailAlertChannel.fromId(123)

new ApiCheck("existing-channel-check", {
  name: "Check with Existing Channel",
  alertChannels: [existingEmailChannel],
  request: {
    method: "GET",
    url: "https://api.acme.com/endpoint",
  },
})