Rate limits and pacing

Requests per key

Each key can make 120 requests a minute. Email checks, through POST /verify, POST /find and GET /email-domains, have their own limit: 20 a minute and 300 a day for each account. Tell us if you need more.

Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and X-Credits-Remaining says how many credits you have left this period.

Retry-After

Over the limit, a request gets a 429 with the code rate_limited, and a Retry-After header with the number of seconds to wait. Wait that long, then try again.

async function call(path, body) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch(`https://api.magpie-cloud.com/v1${path}`, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.MAGPIE_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
      signal: AbortSignal.timeout(90_000),
    });
    if (res.status !== 429 || attempt === 5) return res;
    // Wait as long as we're told, then try again.
    const seconds = Number(res.headers.get("Retry-After")) || 10;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

import os
import time
import requests

def call(path, body):
    for attempt in range(1, 6):
        res = requests.post(
            f"https://api.magpie-cloud.com/v1{path}",
            json=body,
            headers={"Authorization": f"Bearer {os.environ['MAGPIE_API_KEY']}"},
            timeout=90,
        )
        if res.status_code != 429 or attempt == 5:
            return res
        # Wait as long as we're told, then try again.
        time.sleep(int(res.headers.get("Retry-After", 10)))

How checks are paced

Verification and the finder ask other companies' mail servers, and a mail server asked too much, too fast, starts to refuse. So checks are paced on our side, whatever your own limit:

• Per mail provider: each of our servers asks each provider only so often. Google and Microsoft are paced hardest.
• Per company: a short first burst, then about 4 checks a minute, across all our servers.
• Per company, per day: a cap on guesses the mail server rejects. Checks that find a real mailbox don't count.
• IP health: every 6 hours each of our verification IP addresses is checked against spam blocklists, with its reverse DNS and SPF. One on a blocklist is benched until a check finds it clean.

A check may wait its turn, so a call can take longer than usual when you send many at one company. Give your HTTP client a long timeout, such as 90 seconds, and spread work at one company over time.

Daily sending limits

Gmail and Outlook trust a new sender that starts small and grows, and send one that sends everything at once to spam. MagpieCRM on Magpie Cloud gives each workspace a daily limit that starts low and steps up each week its email is received well; the email sending API is planned to work the same way. These are the limits MagpieCRM uses today:

Cold email goes to people who haven't asked to hear from you; opt-in email to people who signed up. Each sending domain gets a reputation score out of 100% from the last 7 days, once 30 emails have gone out: 80% and over is good, under 50% is poor. A good week moves the limit up; a poor one moves it down.

The details, including the signals behind the score, are in MagpieCRM's sending docs.