Skip to main content Implement Instantly rate limiting, backoff, and idempotency patterns.
Use when handling rate limit errors, implementing retry logic,
or optimizing API request throughput for Instantly.
Trigger with phrases like "instantly rate limit", "instantly throttling",
"instantly 429", "instantly retry", "instantly backoff".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill instantly-rate-limits ai automation claude-code devops mcp ai-agents
Instantly Rate Limits
Overview
Handle Instantly API v2 rate limits. The API returns 429 Too Many Requests when limits are exceeded. Most endpoints follow standard limits. The email listing endpoint has a stricter constraint of 20 requests per minute . Failed webhook deliveries are retried up to 3 times within 30 seconds .
Prerequisites
Completed instantly-install-auth setup
Understanding of exponential backoff patterns
Known Rate Limits
Endpoint Limit Notes Most API endpoints Standard REST limits Varies by plan GET /emails20 req/min Stricter — email listing Webhook deliveries 3 retries in 30s Instantly retries to your endpoint Background jobs
Async — poll via GET /background-jobs/{id}
Instructions
Step 1: Exponential Backoff with Jitter import { InstantlyApiError } from "./src/instantly/client";
interface RetryOptions {
maxRetries: number;
baseDelayMs: number;
maxDelayMs: number;
}
const DEFAULT_RETRY: RetryOptions = {
maxRetries: 5,
baseDelayMs: 1000,
maxDelayMs: 30000,
};
async function withBackoff<T>(
operation: () => Promise<T>,
opts: Partial<RetryOptions> = {}
): Promise<T> {
const { maxRetries, baseDelayMs, maxDelayMs } = { ...DEFAULT_RETRY, ...opts };
for (let attempt = 0; attempt <= maxRetries; attempt++) {
try {
return await operation();
} catch (err) {
const isRetryable =
err instanceof InstantlyApiError &&
(err.status === 429 || err.status >= 500);
if (!isRetryable || attempt === maxRetries) throw err;
// Parse Retry-After header if available
let delay = baseDelayMs * Math.pow(2, attempt);
delay = Math.min(delay, maxDelayMs);
// Add jitter (10-30% of delay)
const jitter = delay * (0.1 + Math.random() * 0.2);
const totalDelay = delay + jitter;
console.warn(
`Rate limited (attempt ${attempt + 1}/${maxRetries}). Waiting ${Math.round(totalDelay)}ms...`
);
await new Promise((r) => setTimeout(r, totalDelay));
}
}
throw new Error("Unreachable");
}
Step 2: Request Queue with Concurrency Control class RequestQueue {
private queue: Array<() => Promise<void>> = [];
private running = 0;
private readonly maxConcurrent: number;
private readonly delayBetweenMs: number;
constructor(maxConcurrent = 5, delayBetweenMs = 200) {
this.maxConcurrent = maxConcurrent;
this.delayBetweenMs = delayBetweenMs;
}
async add<T>(operation: () => Promise<T>): Promise<T> {
return new Promise((resolve, reject) => {
this.queue.push(async () => {
try {
const result = await withBackoff(operation);
resolve(result);
} catch (err) {
reject(err);
} finally {
this.running--;
this.processQueue();
}
});
this.processQueue();
});
}
private async processQueue() {
while (this.running < this.maxConcurrent && this.queue.length > 0) {
const task = this.queue.shift()!;
this.running++;
if (this.delayBetweenMs > 0) {
await new Promise((r) => setTimeout(r, this.delayBetweenMs));
}
task();
}
}
}
// Usage — add 500 leads with controlled concurrency
const queue = new RequestQueue(3, 300); // 3 concurrent, 300ms gap
for (const lead of leads) {
queue.add(() =>
instantly("/leads", {
method: "POST",
body: JSON.stringify({ campaign: campaignId, email: lead.email, ...lead }),
})
);
}
Step 3: Rate-Limited Email Listing // The /emails endpoint has a 20 req/min limit
// Use a dedicated throttled fetcher
class ThrottledEmailFetcher {
private requestTimestamps: number[] = [];
private readonly maxPerMinute = 18; // leave 2 req margin
private async waitForSlot() {
const now = Date.now();
this.requestTimestamps = this.requestTimestamps.filter(
(t) => now - t < 60000
);
if (this.requestTimestamps.length >= this.maxPerMinute) {
const oldest = this.requestTimestamps[0];
const waitMs = 60000 - (now - oldest) + 1000; // +1s buffer
console.log(`Email API throttle: waiting ${waitMs}ms`);
await new Promise((r) => setTimeout(r, waitMs));
}
this.requestTimestamps.push(Date.now());
}
async listEmails(params: {
campaign_id?: string;
is_unread?: boolean;
limit?: number;
starting_after?: string;
}) {
await this.waitForSlot();
const qs = new URLSearchParams();
if (params.campaign_id) qs.set("campaign_id", params.campaign_id);
if (params.is_unread !== undefined) qs.set("is_unread", String(params.is_unread));
if (params.limit) qs.set("limit", String(params.limit));
if (params.starting_after) qs.set("starting_after", params.starting_after);
return instantly(`/emails?${qs}`);
}
}
Step 4: Batch Operations Pattern // Instead of creating leads one-by-one, batch where possible
async function addLeadsBatched(
campaignId: string,
leads: Array<{ email: string; first_name?: string }>,
batchSize = 10,
delayBetweenBatchesMs = 1000
) {
let added = 0;
let failed = 0;
for (let i = 0; i < leads.length; i += batchSize) {
const batch = leads.slice(i, i + batchSize);
const results = await Promise.allSettled(
batch.map((lead) =>
withBackoff(() =>
instantly("/leads", {
method: "POST",
body: JSON.stringify({
campaign: campaignId,
email: lead.email,
first_name: lead.first_name,
skip_if_in_workspace: true,
}),
})
)
)
);
added += results.filter((r) => r.status === "fulfilled").length;
failed += results.filter((r) => r.status === "rejected").length;
console.log(`Batch ${Math.floor(i / batchSize) + 1}: ${added} added, ${failed} failed`);
if (i + batchSize < leads.length) {
await new Promise((r) => setTimeout(r, delayBetweenBatchesMs));
}
}
console.log(`\nTotal: ${added} added, ${failed} failed out of ${leads.length}`);
}
Error Handling Error Cause Solution 429 on lead importToo many sequential POSTs Use batch pattern with delays 429 on email listing>20 req/min Use ThrottledEmailFetcher 5xx intermittentInstantly server overload Backoff + retry; check status.instantly.ai Webhook delivery retries exhausted Your endpoint too slow Return 200 immediately, process async Queue memory growing Too many queued operations Set max queue size, reject overflow
Resources
Next Steps For security patterns, see instantly-security-basics.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
