Batch Email Sending

How it works

We handle the rate limits, the exponential backoff, and the background queueing so you don't have to build any of that complex infrastructure yourself. Unlike /api/send which delivers immediately and blocks until done, /api/batch accepts your full recipient list, queues a background job, and returns a batchId instantly. Our background workers then drip the emails out one at a time, perfectly paced to stay under Google's radar. You just poll /api/batch/:id to track the progress!

Step 1: Send the batch

Request body fields

Recipient object

Response: 202 Accepted

{
  "success": true,
  "batchId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "total": 2,
  "status": "queued"
}

Step 2: Poll for progress

Response

{
  "success": true,
  "batchId": "64f1a2b3c4d5e6f7a8b9c0d1",
  "status": "processing",
  "total": 2,
  "sent": 1,
  "failed": 0,
  "progress": 50,
  "recipients": [
    { "email": "john@example.com", "status": "sent", "messageId": "18b3f...", "error": null },
    { "email": "jane@example.com", "status": "pending", "messageId": null, "error": null }
  ]
}

Job statuses

Limits

The recipient cap matches Gmail's own daily sending limit for the connected account. If your batch hits the daily limit mid-send (e.g., you already sent emails earlier today), the job status will change to paused_limit_reached. You do not need to do anything! Sendlib automatically tracks Gmail's 24-hour rolling quota and will automatically resume sending the remaining recipients as soon as your limit resets. To send to more people immediately without waiting, connect additional Gmail accounts and split batches across them using different from addresses.

Error responses