Rate Limits

The Ark API has two types of limits to ensure fair usage and platform stability:

Rate Limits: Control how many API requests you can make per second
Send Limits: Control how many emails you can send per hour

Limit	Value
Requests per second	10

Rate limits are applied per API key using a sliding window algorithm.

Rate Limit Headers

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per second
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when limit resets
`Retry-After`	Seconds to wait (only on 429 responses)

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1705312800

Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "suggestion": "Wait before retrying"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

All Ark SDKs automatically handle rate limits with exponential backoff.

Send Limits

Send limits control the maximum number of emails you can send per hour:

Limit	Default Value
Emails per hour	100

What Happens When You Hit the Limit

New emails are held in a queue until capacity is available
Emails are not rejected, just delayed
The limit resets at the top of each hour

Send Limit Headers

Email-sending endpoints (POST /emails, POST /emails/batch, POST /emails/raw) include send limit headers:

Header	Description
`X-SendLimit-Limit`	Maximum emails per hour (omitted if unlimited)
`X-SendLimit-Used`	Emails sent in current hour
`X-SendLimit-Remaining`	Emails remaining in current hour (omitted if unlimited)
`X-SendLimit-Reset`	Unix timestamp when limit resets (top of next hour)

Example Response Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1705312260
X-SendLimit-Limit: 100
X-SendLimit-Used: 42
X-SendLimit-Remaining: 58
X-SendLimit-Reset: 1705312800

If you have unlimited sending, the X-SendLimit-Limit and X-SendLimit-Remaining headers are omitted.

Checking Your Limits Programmatically

Use the GET /usage endpoint to check your current usage status:

curl https://api.arkhq.io/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

SDK Automatic Retries

All Ark SDKs automatically handle rate limits with exponential backoff:

Python
Node.js
Ruby
Go

from ark import Ark

# SDKs automatically retry rate-limited requests
# Default: 2 retries with exponential backoff
client = Ark()

# Customize retry behavior
client = Ark(max_retries=5)  # More retries
client = Ark(max_retries=0)  # Disable retries

import Ark from 'ark';

// SDKs automatically retry rate-limited requests
// Default: 2 retries with exponential backoff
const client = new Ark();

// Customize retry behavior
const client = new Ark({ maxRetries: 5 });  // More retries
const client = new Ark({ maxRetries: 0 });  // Disable retries

require "ark_email"

# SDKs automatically retry rate-limited requests
# Default: 2 retries with exponential backoff
client = ArkEmail::Client.new

# Customize retry behavior
client = ArkEmail::Client.new(max_retries: 5)  # More retries
client = ArkEmail::Client.new(max_retries: 0)  # Disable retries

import (
    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

// SDKs automatically retry rate-limited requests
// Default: 2 retries with exponential backoff
client := ark.NewClient()

// Customize retry behavior
client := ark.NewClient(option.WithMaxRetries(5))  // More retries
client := ark.NewClient(option.WithMaxRetries(0))  // Disable retries

Best Practices

1. Use SDK Auto-Retries

The SDKs handle rate limits automatically. Just send your requests and they’ll retry with backoff:

Python
Node.js

# Just send emails - SDK handles rate limits automatically
for user in users:
    client.emails.send(
        from_="notifications@yourdomain.com",
        to=[user.email],
        subject="Update",
        html="<p>Hello!</p>"
    )

// Just send emails - SDK handles rate limits automatically
for (const user of users) {
  await client.emails.send({
    from: 'notifications@yourdomain.com',
    to: [user.email],
    subject: 'Update',
    html: '<p>Hello!</p>',
  });
}

2. Use Batch Endpoints

Instead of making multiple individual requests, use the batch endpoint:

Python
Node.js
Ruby
Go

# Instead of this (100 requests)
for email in emails:
    client.emails.send(**email)

# Do this (1 request)
client.emails.send_batch(emails=emails)

// Instead of this (100 requests)
for (const email of emails) {
  await client.emails.send(email);
}

// Do this (1 request)
await client.emails.sendBatch({ emails });

# Instead of this (100 requests)
emails.each { |email| client.emails.send_(**email) }

# Do this (1 request)
client.emails.send_batch(emails: emails)

// Instead of this (100 requests)
for _, email := range emails {
    client.Emails.Send(ctx, email)
}

// Do this (1 request)
client.Emails.SendBatch(ctx, ark.EmailSendBatchParams{
    Emails: emails,
})

3. Monitor Your Usage

Check your usage regularly with the usage endpoint or dashboard:

usage = client.usage.retrieve()

if usage.send_limit.limit:
    percent_used = (usage.send_limit.used / usage.send_limit.limit) * 100
    if percent_used > 80:
        print(f"Warning: {percent_used:.0f}% of hourly send limit used")

4. Use Exponential Backoff

The SDKs handle exponential backoff automatically. Configure the number of retries:

Python
Node.js
Ruby
Go

from ark import Ark

# Configure max retries - SDK uses exponential backoff automatically
client = Ark(max_retries=5)

# All requests will retry up to 5 times with exponential backoff
# for rate limits, timeouts, and server errors
email = client.emails.send(
    from_="hello@yourdomain.com",
    to=["user@example.com"],
    subject="Hello",
    html="<p>Hello!</p>"
)

import Ark from 'ark';

// Configure max retries - SDK uses exponential backoff automatically
const client = new Ark({ maxRetries: 5 });

// All requests will retry up to 5 times with exponential backoff
// for rate limits, timeouts, and server errors
const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: ['user@example.com'],
  subject: 'Hello',
  html: '<p>Hello!</p>',
});

require "ark_email"

# Configure max retries - SDK uses exponential backoff automatically
client = ArkEmail::Client.new(max_retries: 5)

# All requests will retry up to 5 times with exponential backoff
# for rate limits, timeouts, and server errors
email = client.emails.send_(
  from: "hello@yourdomain.com",
  to: ["user@example.com"],
  subject: "Hello",
  html: "<p>Hello!</p>"
)

import (
    "github.com/ArkHQ-io/ark-go"
    "github.com/ArkHQ-io/ark-go/option"
)

// Configure max retries - SDK uses exponential backoff automatically
client := ark.NewClient(option.WithMaxRetries(5))

// All requests will retry up to 5 times with exponential backoff
// for rate limits, timeouts, and server errors
email, _ := client.Emails.Send(ctx, ark.EmailSendParams{
    From:    "hello@yourdomain.com",
    To:      []string{"user@example.com"},
    Subject: "Hello",
    HTML:    ark.String("<p>Hello!</p>"),
})

Endpoint-Specific Limits

Email Sending

Endpoint	Limit	Value
`POST /emails`	To recipients	50 per email
`POST /emails`	CC recipients	50 per email
`POST /emails`	BCC recipients	50 per email
`POST /emails`	Subject length	998 characters
`POST /emails`	Tag length	1000 characters

Batch Emails

Endpoint	Limit	Value
`POST /emails/batch`	Emails per request	100
`POST /emails/batch`	Recipients per email	50
`POST /emails/batch`	Total recipients	1000 across all emails

Pagination

Endpoint	Default	Maximum
`GET /emails`	30 per page	100 per page
`GET /suppressions`	30 per page	100 per page

Suppressions

Endpoint	Limit	Value
`POST /suppressions/bulk`	Suppressions per request	1000

Need Higher Limits?

If you need higher rate limits or send limits for your use case, contact us:

Contact Support

Request higher limits for your needs

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

Rate Limits — API Request & Email Send Quotas

Rate Limits

Rate Limit Headers

Example Response Headers

Handling Rate Limits

Send Limits

What Happens When You Hit the Limit

Send Limit Headers

Example Response Headers

Checking Your Limits Programmatically

SDK Automatic Retries

Best Practices

1. Use SDK Auto-Retries

2. Use Batch Endpoints

3. Monitor Your Usage

4. Use Exponential Backoff

Endpoint-Specific Limits

Email Sending

Batch Emails

Suppressions

Need Higher Limits?

Contact Support

Getting Started

White-Label Email Architecture

Sending Email

Domain Setup

Webhooks

Tracking & Deliverability

Concepts

Migration

Reference

​Rate Limits

​Rate Limit Headers

​Example Response Headers

​Handling Rate Limits

​Send Limits

​What Happens When You Hit the Limit

​Send Limit Headers

​Example Response Headers

​Checking Your Limits Programmatically

​SDK Automatic Retries

​Best Practices

​1. Use SDK Auto-Retries

​2. Use Batch Endpoints

​3. Monitor Your Usage

​4. Use Exponential Backoff

​Endpoint-Specific Limits

​Email Sending

​Batch Emails

​Pagination

​Suppressions

​Need Higher Limits?

Contact Support

Rate Limits

Rate Limit Headers

Example Response Headers

Handling Rate Limits

Send Limits

What Happens When You Hit the Limit

Send Limit Headers

Example Response Headers

Checking Your Limits Programmatically

SDK Automatic Retries

Best Practices

1. Use SDK Auto-Retries

2. Use Batch Endpoints

3. Monitor Your Usage

4. Use Exponential Backoff

Endpoint-Specific Limits

Email Sending

Batch Emails

Pagination

Suppressions

Need Higher Limits?