Limits and retries

Request rate

Limits are counted per project: all of a project's keys, and sends from the dashboard, share one allowance.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Over the limit, the answer is 429 rate_limited with the seconds to wait in Retry-After. To reach many recipients use the /bulk endpoints: up to 1,000 in one request.

Per-recipient caps

These stop a bug or an attack from flooding one person and burning your credits.

• Change the caps in the dashboard under Settings → Sending.
• A single send over the cap answers 429 recipient_rate_limited with a Retry-After header. Nothing is charged.
• In a batch, a capped recipient's message becomes failed with error recipient_rate_limited and is refunded. The rest are sent.

Idempotency

When the network drops or a request times out, you cannot tell whether it arrived. Add an Idempotency-Key header to a send request, and a repeat with the same key sends nothing new: it returns the original result.

curl -X POST https://api.wesend.mn/v1/sms \
  -H "Authorization: Bearer $WESEND_API_KEY" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "99112233",
  "text": "Tanii zahialga batalgaajlaa. #1042"
}'

• A key is 1 to 255 printable ASCII characters. Use something unique from your own system, such as an order number.
• It works on /sms, /sms/bulk, /email and /email/bulk. A key is unique within the project.
• If the original send failed, the repeat reports that failure again. To send anew, use a new key.

Size limits