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 /emails | 20 req/min | Stricter — email listing |
| Webhook deliveries | 3 retries in 30s | Instantly retries to your endpoint |
| Background jobs | N/A | 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;
let delay = baseDelayMs * Math.pow(2, attempt);
delay = Math.min(delay, maxDelayMs);
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--;
.();
}
});
.();
});
}
() {
(. < . && .. > ) {
task = ..()!;
.++;
(. > ) {
( (r, .));
}
();
}
}
}
queue = (, );
( lead leads) {
queue.(
(, {
: ,
: .({ : campaignId, : lead., ...lead }),
})
);
}
Step 3: Rate-Limited Email Listing
class ThrottledEmailFetcher {
private requestTimestamps: number[] = [];
private readonly maxPerMinute = 18;
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;
console.log(`Email API throttle: waiting ${waitMs}ms`);
await new Promise((r) => setTimeout(r, waitMs));
}
..(.());
}
() {
.();
qs = ();
(params.) qs.(, params.);
(params. !== ) qs.(, (params.));
(params.) qs.(, (params.));
(params.) qs.(, params.);
();
}
}
Step 4: Batch Operations Pattern
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. === ).;
failed += results.( r. === ).;
.();
(i + batchSize < leads.) {
( (r, delayBetweenBatchesMs));
}
}
.();
}
Error Handling
| Error | Cause | Solution |
|---|
429 on lead import | Too many sequential POSTs | Use batch pattern with delays |
429 on email listing | >20 req/min | Use ThrottledEmailFetcher |
5xx intermittent | Instantly 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.
