How to handle rate-limit exception in MailSlurp

A guide to reduce rate-limit exceptions when using HTTP APIs

MailSlurp's API imposes a limit of 150 requests per second. This is to ensure smooth operation of the API for all users and to catch common exceptions such as infinite loops. When a rate limit is reached your request may fail with a 429 response status code.

Identify the cause

If your system is being rate-limited please identify the cause. There is typically a place in your code that is calling MailSlurp very frequently. Common causes of rate limiting are:

  • Calling MailSlurp inside a loop (batch your requests or add a timeout between requests)
  • Your system is under heavy load and passing that to MailSlurp (think about design changes including webhooks)
  • You are running automated tests or load testing (MailSlurp does not support load testing)

Batch requests

Plans that support bulk operations allow you to batch operations. This can reduce requests significantly. If you create inboxes or send emails within a loop use the loop to build a request object and then send the request once outside the loop using the BulkActionsControllerApi. Here is an example in Java:

public class BulkUsageExample {
  public static void main(String[] args) {
    // configure api client
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    ApiKeyAuth API_KEY = (ApiKeyAuth) defaultClient.getAuthentication("API_KEY");
    API_KEY.setApiKey("YOUR API KEY");

    // setup bulk controller
    BulkActionsControllerApi apiInstance = new BulkActionsControllerApi(defaultClient);

    Integer count = 56; // Integer | Number of inboxes to be created in bulk
    try {
      List<InboxDto> result = apiInstance.bulkCreateInboxes(count);
    } catch (ApiException e) {

Use webhook push

You can configure MailSlurp to send emails and other events directly to your server using HTTP Push Webhooks. You can create webhooks in the dashboard or using code. Each inbox can be assigned a new webhook or use an existing one. New inboxes must be connected to a webhook if you wish to receive events for the inbox. Here is an example of creating a webhook in Java:

WebhookControllerApi apiInstance = new WebhookControllerApi(defaultClient);
CreateWebhookOptions createWebhookOptions = new CreateWebhookOptions(); 
try {
  WebhookDto result = apiInstance.createWebhook(inboxId, createWebhookOptions);
} catch (ApiException e) {
  System.err.println("Exception when calling WebhookControllerApi#createWebhook");
  System.err.println("Status code: " + e.getCode());
  System.err.println("Reason: " + e.getResponseBody());
  System.err.println("Response headers: " + e.getResponseHeaders());

To setup the webhook see the webhook creation options. You will need to create a publicly accessible endpoint (you can add basic auth if you wish) so that MailSlurp can POST the event payload to your server. Each webhook can consume a single event type. Each event type has a different payload. These payload classes are included in each SDK. The NEW_EMAIL event payload for the Java API can be found here.

Avoid tight loops

If you are calling MailSlurp within a loop it is best to avoid this all together. If you cannot then try adding a sleep or timeout of 20 milliseconds between requests. This will slow down your loop slightly but will also reduce the number of requests per second that are reaching MailSlurp and likely prevent rate limit exceptions.

while(condition) {
	// call MailSlurp
	// sleep for some time

Requests support

If you have tried these techniques please open a ticket with support to discuss raising your rate limit. Please tell support what your use case is so they can more accurately diagnose the case and offer increases.

Contact support and explain your situation

Ready to dive in?Start building email applications today.