Instantly Observability
Overview
Build monitoring and alerting for Instantly integrations. Covers campaign health checks, account warmup monitoring, webhook delivery tracking, deliverability alerts, and performance dashboards. Uses Instantly API v2 analytics endpoints combined with webhook events for real-time awareness.
Prerequisites
- Completed
instantly-install-auth setup
- API key with
campaigns:read, accounts:read, and all:read scopes
- Notification channel (Slack, email, PagerDuty, etc.)
Instructions
Step 1: Campaign Health Monitor
import { InstantlyClient } from "./src/instantly/client";
const client = new InstantlyClient();
interface HealthCheck {
check: string;
status: "ok" | "warning" | "critical";
message: string;
}
async function campaignHealthCheck(): Promise<HealthCheck[]> {
const checks: HealthCheck[] = [];
const campaigns = await client.campaigns.list(100);
for (const campaign of campaigns.filter((c) => c.status === 1)) {
const analytics = await client.campaigns.analytics(campaign.id);
const sent = analytics.emails_sent || 1;
const bounceRate = (analytics.emails_bounced / sent) * 100;
if (bounceRate > 5) {
checks.push({
check: `bounce_rate:${campaign.name}`,
status: "critical",
message: `Bounce rate ${bounceRate.toFixed(1)}% exceeds 5% threshold. Campaign may be auto-paused.`,
});
} else if (bounceRate > 3) {
checks.push({
check: `bounce_rate:${campaign.name}`,
status: "warning",
message: `Bounce rate ${bounceRate.toFixed(1)}% approaching 5% threshold.`,
});
}
const replyRate = (analytics.emails_replied / sent) * 100;
if (replyRate < 1 && sent > 100) {
checks.push({
check: `reply_rate:${campaign.name}`,
status: "warning",
message: `Reply rate ${replyRate.toFixed(1)}% is below 1% after ${sent} sends. Review email copy.`,
});
}
const openRate = (analytics.emails_opened / sent) * 100;
if (openRate < 20 && sent > 100) {
checks.push({
check: `open_rate:${campaign.name}`,
status: "warning",
message: `Open rate ${openRate.toFixed(1)}% below 20%. Check subject lines and deliverability.`,
});
}
}
const unhealthy = campaigns.filter((c) => c.status === -1);
const bounceProtected = campaigns.filter((c) => c.status === -2);
if (unhealthy.length > 0) {
checks.push({
check: "unhealthy_campaigns",
status: "critical",
message: `${unhealthy.length} campaign(s) in Accounts Unhealthy state: ${unhealthy.map((c) => c.name).join(", ")}`,
});
}
if (bounceProtected.length > 0) {
checks.push({
check: "bounce_protected_campaigns",
status: "critical",
message: `${bounceProtected.length} campaign(s) paused by Bounce Protect: ${bounceProtected.map((c) => c.name).join(", ")}`,
});
}
return checks;
}
Step 2: Account Warmup Monitor
async function warmupHealthCheck(): Promise<HealthCheck[]> {
const checks: HealthCheck[] = [];
const accounts = await client.accounts.list(100);
const emails = accounts.map((a) => a.email);
if (emails.length === 0) return checks;
const warmup = await client.accounts.warmupAnalytics(emails);
for (const w of warmup as Array<{
email: string;
warmup_emails_sent: number;
warmup_emails_landed_inbox: number;
warmup_emails_landed_spam: number;
}>) {
const sent = w.warmup_emails_sent || 1;
const inboxRate = (w.warmup_emails_landed_inbox / sent) * 100;
const spamRate = (w.warmup_emails_landed_spam / sent) * 100;
if (inboxRate < ) {
checks.({
: ,
: inboxRate < ? : ,
: ,
});
}
(spamRate > ) {
checks.({
: ,
: ,
: ,
});
}
}
vitals = client..(emails) <{
: ; : ; : ;
}>;
broken = vitals.( v. !== || v. !== );
(broken. > ) {
checks.({
: ,
: ,
: ,
});
}
checks;
}
Step 3: Webhook Delivery Monitor
async function webhookHealthCheck(): Promise<HealthCheck[]> {
const checks: HealthCheck[] = [];
const summary = await client.request<{
total_delivered: number;
total_failed: number;
total_pending: number;
}>("/webhook-events/summary");
if (summary.total_failed > 0) {
const failRate = (summary.total_failed / (summary.total_delivered + summary.total_failed)) * 100;
checks.push({
check: "webhook_delivery",
status: failRate > 10 ? "critical" : "warning",
message: `Webhook delivery: ${summary.total_delivered} delivered, ${summary.total_failed} failed (${failRate.toFixed(1)}% fail rate)`,
});
}
const webhooks = await client.webhooks.list();
const paused = webhooks.filter((w: ) => w. === );
(paused. > ) {
checks.({
: ,
: ,
: ,
});
}
checks;
}
Step 4: Alerting Pipeline
async function runHealthChecks() {
console.log(`\n=== Instantly Health Check — ${new Date().toISOString()} ===\n`);
const allChecks: HealthCheck[] = [
...await campaignHealthCheck(),
...await warmupHealthCheck(),
...await webhookHealthCheck(),
];
for (const check of allChecks) {
const icon = check.status === "ok" ? "OK" : check.status === "warning" ? "WARN" : "CRIT";
console.log(`[${icon}] ${check.check}: ${check.message}`);
}
const critical = allChecks.filter((c) => c.status === "critical");
const warnings = allChecks.filter((c) => c.status === "warning");
if (critical. > ) {
(, critical);
}
(warnings. > ) {
(, warnings);
}
.();
}
() {
color = severity === ? : ;
text = checks.( ).();
(process..!, {
: ,
: { : },
: .({
: [{
color,
: ,
text,
: .(.() / ),
}],
}),
});
}
Step 5: Scheduled Monitoring (Cron)
import cron from "node-cron";
cron.schedule("*/15 * * * *", async () => {
try {
await runHealthChecks();
} catch (err) {
console.error("Health check failed:", err);
await sendAlert("critical", [{ check: "monitor", status: "critical", message: `Monitor itself failed: ${err}` }]);
}
});
Dashboard Metrics Summary
| Metric | Source | Alert Threshold |
|---|
| Campaign bounce rate | GET /campaigns/analytics | >5% critical |
| Campaign reply rate | GET /campaigns/analytics | <1% warning |
| Campaign open rate | GET /campaigns/analytics | <20% warning |
| Warmup inbox rate | POST /accounts/warmup-analytics | <80% warning, <60% critical |
| Account vitals | POST /accounts/test/vitals | Any non-ok = critical |
| Webhook delivery | GET /webhook-events/summary | >10% fail rate = critical |
| Unhealthy campaigns | GET /campaigns | status=-1 = critical |
| Bounce protected campaigns | GET /campaigns | status=-2 = critical |
Error Handling
| Error | Cause | Solution |
|---|
| Monitor itself rate-limited | Too-frequent checks | Increase interval to 15-30 min |
| Slack alert not delivered | Invalid webhook URL | Verify SLACK_WEBHOOK_URL |
| Stale analytics data | Instantly updates delay | Allow 1-hour data lag |
Resources
- Instantly Analytics API
- Instantly Account API
- Instantly Webhook Events
Next Steps
For incident response, see instantly-incident-runbook.
