Rate limits - Deliveryman AI

There are two kinds of limits. Request limits cap how many API calls your account can make per minute. Send pacing controls how fast emails leave each of your sending domains.

Strongly recommended: leave 5 to 10 minutes between emails sent from the same domain. Sending many emails from one domain in a short time can hurt your domain and IP reputation. The limits below are the most the API will accept, not a pace to send at.

Request limits

Each account has its own limits, so other accounts never use up yours. All the API keys on your account count toward the same limits.

Endpoints	Limit
Send Email	60 requests per minute
Retrieve Sent Email, List Sent Emails and List Replies	120 requests per minute in total across these three
Verify Email	20 requests per minute
List, add and remove suppressed emails	60 requests per minute in total across list, add and remove

Each count resets at the start of every minute. Over the limit, the API returns 429 with a Retry-After header that tells you how many seconds are left until the reset:

HTTP/1.1 429 Too Many Requests
Retry-After: 23
Content-Type: application/json

{
  "message": "Too many requests. Please retry in 23 seconds."
}

Wait that many seconds before you retry. Any request sent before then fails the same way.

Send pacing

Emails from the same sending domain go out at least a minimum interval apart. The interval is set by Deliveryman and applies to each domain separately, so two domains don’t slow each other down. If you call Send Email before the interval has passed, the email is queued instead of rejected:

The response is 202 with status: "scheduled" and the time it will go out in scheduled_for.
The message_id works right away, so you can follow the email with Retrieve Sent Email while it waits. You also get a sent webhook when it goes out.
A scheduled email can’t be used as reply_to_message_id until it has gone out. Trying returns 409.
If the email can’t be sent when its time comes, for example because you ran out of credits, you get a failed webhook and its status becomes failed.

Each domain’s queue holds a limited number of emails. Once it’s full, Send Email returns 429 until some of the queued emails have gone out.

Handling a 429

Both kinds of 429 have a message field. A request limit response also has the Retry-After header. A full send queue doesn’t, since it depends on when the queued emails go out.

For a request limit, wait for Retry-After and retry.
For a full queue, stop sending from that domain for a while. Watch for sent webhooks to know when the queue has room again.

​Request limits

​Send pacing

​Handling a 429

Request limits

Send pacing

Handling a 429