checkly · guolau · May 15, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/constructs/alert-channel.mdx b/constructs/alert-channel.mdx
@@ -0,0 +1,46 @@
+---
+title: 'Alert Channel Overview'
+description: 'Learn how to configure alert channels with the Checkly CLI.'
+sidebarTitle: 'Overview'
+---
+
+import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx';
+
+Alert channels let you get alert notifications when a check or monitor fails. [Learn more about alerting in our docs](/communicate/alerts/overview/).
+
+## Common properties
+
+All alert channels share a set of common properties to define when / how they should alert derived from the abstract class
+`AlertChannel`.
+
+<AlertChannelOptionsTable />
+
+Alert channels are assigned to checks, monitors, and groups by instantiating a class and adding the resulting object to the
+`alertChannels` array. 
+
+To assign alert channels to `CheckGroupV2` constructs, you'll also need to set the [`alertEscalationPolicy`](/constructs/check-group-v2#param-alert-escalation-policy) to enable the group alerting override.
+
+## Using `fromId()` to reference an existing channel 
+
+You can reference an existing alert channel in your Checkly account using the `fromId()` method on any `AlertChannel`
+class. When your CLI project is responsible for creating and managing alert channels, it integrates seamlessly with Checkly's deployment control mechanisms. This ensures that any changes made are thoroughly validated.
+
+For users with multiple Checkly CLI projects:
+
+- Alert channels can be set up through the Checkly UI or any other method, ensuring they remain intact and unaffected by individual CLI project operations.
+
+For users managing a single Checkly CLI project:
+
+- The entire process of creating and subscribing to alert channels can be handled within that single project. This is made possible because the project references the logical ID of the alert channel, rather than an ID generated post-deployment.
+
+<Note>
+If you attempt to deploy a project that references alert channels which have been removed or are no longer valid, the deployment process will not proceed. This feature helps maintain the integrity and reliability of your monitoring and alerting setup.
+</Note>
+
+```ts
+export const emailChannel = EmailAlertChannel.fromId(20)
+```
+
+You can obtain the ID for your alert channel either from the [Checkly web UI](https://app.checklyhq.com/accounts/alerts/settings) or by utilizing our [REST API](/api-reference/alert-channels/list-all-alert-channels/).
+
+![email channel id](/images/docs/images/cli/constructs_email_id@2x.jpg)
diff --git a/constructs/email-alert-channel.mdx b/constructs/email-alert-channel.mdx
@@ -1,13 +1,14 @@
 ---
 title: 'EmailAlertChannel Construct'
 description: 'Learn how to configure email alert channels with the Checkly CLI.'
-sidebarTitle: 'Email Alert Channel'
+sidebarTitle: 'Email'
 ---
 
 import AlertChannelOptionsTable from '/snippets/alert-channel-options-table.mdx';
+import AlertChannelOptionsText from '/snippets/alert-channel-options-text.mdx';
 
 <Tip>
-Learn more about Email alerts in [the email alert documentation](/integrations/alerts/email).
+For general information about alerting, see our docs on [email alerts](/integrations/alerts/email) and [alerting with Checkly](/communicate/alerts/overview/).
 </Tip>
 
 Use Email Alert Channels to send email notifications when checks fail or recover.
@@ -37,6 +38,10 @@ const emailChannel = new EmailAlertChannel("ops-email-channel", {
 
 </CodeGroup>
 
+<Note>
+  If you need to reference existing alert channels that were created outside of your CLI project, use [`fromId()`](/constructs/alert-channel#using-fromid-to-reference-an-existing-channel).
+</Note>
+
 ## Configuration
 
 <Tabs>
@@ -59,276 +64,9 @@ Configure Email-specific settings:
 ### Email Alert Channel Options
 
 <ResponseField name="address" type="string" required>
-Email address to send notifications to. Each EmailAlertChannel supports only one email address.
-
-**Usage:**
-
-```ts highlight={2}
-new EmailAlertChannel('team-email', {
-  address: 'dev-team@acme.com'
-})
-```
-
-**Examples:**
-
-<CodeGroup>
-
-```ts Team Notifications
-const teamEmail = new EmailAlertChannel("team-email", {
-  address: "dev-team@acme.com",
-})
-
-new ApiCheck("api-health-check", {
-  name: "API Health Check",
-  alertChannels: [teamEmail],
-  request: {
-    method: "GET",
-    url: "https://api.acme.com/health",
-  },
-})
-```
-
-```ts Individual Developer
-const developerEmail = new EmailAlertChannel("developer-email", {
-  address: "john.doe@acme.com",
-})
-
-new ApiCheck("personal-project-check", {
-  name: "Personal Project Check",
-  alertChannels: [developerEmail],
-  request: {
-    method: "GET",
-    url: "https://johnspersonalapi.com/status",
-  },
-})
-```
-
-</CodeGroup>
-
-**Use cases**: Team notifications, individual alerts, distribution lists, role-based alerting.
+Email address to send notifications to. Each `EmailAlertChannel` supports only one email address, do not use multiple addresses separated by a comma.
 </ResponseField>
 
 ### General Alert Channel Options
 
-<ResponseField name="sendRecovery" type="boolean">
-Whether to send notifications when checks recover from failure or degraded state.
-
-**Usage:**
-
-```ts highlight={3}
-new EmailAlertChannel("recovery-email", {
-  address: "ops@acme.com",
-  sendRecovery: true, // Send recovery notifications
-})
-```
-
-**Examples:**
-
-<CodeGroup>
-
-```ts Recovery Notifications
-const opsEmail = new EmailAlertChannel("ops-email", {
-  address: "ops@acme.com",
-  sendRecovery: true, // Get notified when issues are resolved
-  sendFailure: true,
-})
-```
-
-```ts Failure Only
-const alertsEmail = new EmailAlertChannel("alerts-only", {
-  address: "alerts@acme.com",
-  sendRecovery: false, // Only failures, no recovery notifications
-  sendFailure: true,
-})
-```
-
-</CodeGroup>
-
-**Use cases**: Recovery confirmation, operational awareness, noise reduction.
-</ResponseField>
-
-<ResponseField name="sendFailure" type="boolean">
-Whether to send notifications when checks fail.
-
-**Usage:**
-
-```ts highlight={3}
-new EmailAlertChannel("failure-email", {
-  address: "oncall@acme.com",
-  sendFailure: true, // Send failure notifications
-})
-```
-
-**Examples:**
-
-<CodeGroup>
-
-```ts Failures Only
-const criticalEmail = new EmailAlertChannel("critical-email", {
-  address: "oncall@acme.com",
-  sendFailure: true,
-  sendRecovery: false,
-  sendDegraded: false,
-})
-```
-
-```ts All Notifications
-const comprehensiveEmail = new EmailAlertChannel("all-notifications", {
-  address: "monitoring@acme.com",
-  sendFailure: true,
-  sendRecovery: true,
-  sendDegraded: true,
-})
-```
-
-</CodeGroup>
-
-**Use cases**: Incident response, failure monitoring, operational alerting.
-</ResponseField>
-
-<ResponseField name="sendDegraded" type="boolean">
-
-Whether to send notifications when API checks degrade (performance thresholds exceeded but not failed).
-
-**Usage:**
-
-```ts highlight={3}
-new EmailAlertChannel("performance-email", {
-  address: "performance-team@acme.com",
-  sendDegraded: true, // Send degraded performance notifications
-})
-```
-
-**Use cases**: Performance monitoring, early warning systems, SLA tracking.
-</ResponseField>
-
-<ResponseField name="sslExpiry" type="boolean">
-Whether to send notifications for SSL certificate expiry warnings.
-
-**Usage:**
-
-```ts highlight={3}
-new EmailAlertChannel("security-email", {
-  address: "security@acme.com",
-  sslExpiry: true,
-  sslExpiryThreshold: 30, // Alert 30 days before expiry
-})
-```
-
-**Use cases**: Certificate management, security compliance, proactive maintenance.
-</ResponseField>
-
-<ResponseField name="sslExpiryThreshold" type="number">
-Number of days before SSL certificate expiry to send notifications. Only relevant when `sslExpiry` is enabled.
-
-**Usage:**
-
-```ts highlight={4}
-new EmailAlertChannel("ssl-monitoring", {
-  address: "devops@acme.com",
-  sslExpiry: true,
-  sslExpiryThreshold: 30, // Alert 30 days before expiry
-})
-```
-
-**Use cases**: Certificate renewal planning, compliance management, operational scheduling.
-</ResponseField>
-
-## Examples
-
-<CodeGroup>
-
-```ts Multiple Recipients
-// Create separate channels for different recipients
-const devEmail = new EmailAlertChannel("dev-email", {
-  address: "dev@acme.com",
-  sendDegraded: true,
-})
-
-const opsEmail = new EmailAlertChannel("ops-email", {
-  address: "ops@acme.com",
-  sendFailure: true,
-  sendRecovery: true,
-})
-
-const managerEmail = new EmailAlertChannel("manager-email", {
-  address: "manager@acme.com",
-  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",
-  },
-})
-```
-
-```ts Comprehensive Setup
-// Full configuration example
-const comprehensiveEmail = new EmailAlertChannel("comprehensive-alerts", {
-  address: "monitoring@acme.com",
-  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",
-  },
-})
-```
-
-</CodeGroup>
-
-<Info>
-**Single Email Address**: EmailAlertChannel only accepts one email address. For multiple recipients, create separate EmailAlertChannel instances or use distribution lists.
-</Info>
-
-<Warning>
-**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.
-</Warning>
-
-## 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()`.
-
-<Tabs>
-  <Tab title="Web UI">
-    1. Go to [Alert Channels](https://app.checklyhq.com/alerts/) in your Checkly dashboard
-    2. Find your email channel and note the ID in the URL or channel details
-  </Tab>
-
-  <Tab title="API">
-    ```bash
-    curl -H "Authorization: Bearer YOUR_API_KEY" \
-         -H "X-Checkly-Account: YOUR_ACCOUNT_ID" \
-         https://api.checklyhq.com/v1/alert-channels/
-    ```
-  </Tab>
-</Tabs>
-
-```ts 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",
-  },
-})
-```
+<AlertChannelOptionsText />