Guides

Limits and errors

Limits keep the shared sending infrastructure healthy and protect your domain if a key leaks. Every limit answers with a clear error, so your code can wait and retry.

Request rate

Each company may make 10 requests per second, counted over a sliding one-second window and shared by all of its keys. Every authenticated response except a restricted_api_key error carries the current state:

Over the limit the API answers 429 rate_limit_exceeded and nothing is done. To send many emails, use batches of up to 100 instead of many single requests.

Requests in progress

A company may have 25 requests running at the same time. Request bodies larger than 2 MB (attachments, large batches) are also limited: one at a time per company, and only a few at a time across the platform. Over either limit the API answers 429 rate_limit_exceeded with a retry-after header (1 or 2 seconds) and nothing is done. Send large attachments one after the other rather than in parallel.

Hourly sending limits

Recipients are counted per hour, over the last 60 minutes:

• The company limit is a fair share: no company may use more than a quarter of the platform's hourly capacity, so one busy sender cannot hold up the others. Part of the capacity is always kept for account mail such as invitations, password and security notifications.
• Every address in to, cc and bcc counts as one recipient.
• An email counts in the hour it is handed to the mail server: immediate emails when you send them, scheduled emails when they go out.
• Over the limit, POST /emails and POST /emails/batch answer 429 rate_limit_exceeded (Hourly sending limit reached) and nothing is sent. A scheduled email that hits the limit when it comes due waits five minutes and is tried again.
• The limit for all companies together protects the shared infrastructure and answers the same way in the rare case it is reached.

Monthly allowance

Your company's plan sets how many recipients tsmartSend may send per calendar month. The console shows the usage under Apps → Core services → tsmartSend.

• Recipients count when the email is accepted, including scheduled emails. Emails that failed, were canceled or whose recipients were all suppressed do not count.
• A request that would go over the allowance is refused with 429 monthly_quota_exceeded and nothing is sent.
• Without an active subscription, sending is refused with 403 account_inactive.

Per-email limits

Batch limits

• 1 to 100 emails per request, each within the per-email limits.
• No attachments in batch emails.
• Hourly and monthly limits are checked for all valid emails of the batch together: if they do not fit, none is sent.

Other limits

Errors

Every error has the same JSON body, with the HTTP status repeated in statusCode:

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`subject` is required and must be a single line"
}

Branch on name, not on message: names are stable, messages may be reworded. Unknown paths on the API host also answer in this format (404 not_found).

Errors from the key check (missing_api_key, invalid_api_key, service_disabled, ip_not_allowed) come before the request rate is counted and carry no ratelimit-* headers. A restricted_api_key error (a sending-access key on a full-access endpoint) is counted against the request rate but carries no ratelimit-* headers either.

Handling errors and retrying

• 4xx except 429 and 409 concurrent_idempotent_requests: fix the request; sending it again unchanged gives the same answer.
• 409 concurrent_idempotent_requests: the first request with the same Idempotency-Key is still running. Wait briefly and retry with the same key and the identical body: you get the first request's response once it has finished, or, if it failed, the retry is processed normally.
• 429 for the request rate or for requests in progress: wait retry-after seconds and retry. Nothing was sent.
• 429 for hourly or monthly limits: nothing was sent. Retry later, spread sending over time, or contact us about a larger plan.
• 429 validation_error on POST /domains: 10 domains are waiting for ownership verification. Verify or delete one of them first; retrying sooner does not help.
• 5xx and network errors: retry with the same Idempotency-Key and the identical body. If the first request did go through, you get its response back instead of a second email; if it failed, the key was released and the retry is processed normally.

const { data, error, headers } = await tsmart.emails.send(email, { idempotencyKey: `order-${order.id}/confirmation` });
if (error) {
  switch (error.name) {
    case "monthly_quota_exceeded":
    case "rate_limit_exceeded":
      // Nothing was sent: queue the email and try again later.
      break;
    case "domain_not_verified":
      // Fix the domain's DNS records in the console.
      break;
    default:
      throw new Error(`${error.statusCode} ${error.name}: ${error.message}`);
  }
}

from tsmart import TsmartError

try:
    client.emails.send(email, idempotency_key=f"order-{order_id}/confirmation")
except TsmartError as e:
    if e.name in ("monthly_quota_exceeded", "rate_limit_exceeded"):
        pass  # nothing was sent: queue the email and try again later
    else:
        raise