> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bosonware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

> What BosonWare publishes about sending limits, plan allowances, and defensive practices when API rate limits are not documented.

BosonWare has not published API rate limits for the BosonMail REST API. This page covers what is known about plan-level allowances, client-side limits enforced by the SDK, and defensive practices you can apply while sending at scale.

## Plan outbound allowance

Each BosonMail inbox includes a monthly outbound allowance:

| Allowance | Details |
| - | - |
| 500 emails / month / inbox | Included at no extra charge. |
| Unlimited inbound | No limit on received emails. |
| Free internal email | Unlimited email between inboxes in the same account. |

If you need more outbound volume, BosonWare offers two options:

| Option | Pricing | Validity |
| - | - | - |
| Extra credits | KSh 150 per 1,000 emails | 90 days |
| Higher monthly allowance | KSh 100 per 1,000 emails / month | Ongoing |

> [!NOTE]
>
> Whether emails sent through the SDK and API count against the 500 outbound allowance is likely but not confirmed by BosonWare. Contact [support@bosonware.com](mailto:support@bosonware.com) to verify.

## Client-side limits

The SDK enforces the following limits before any network request is made:

| Limit | Value | Error when exceeded |
| - | - | - |
| Attachments per email | 10 | "A maximum of 10 attachments is allowed" |
| Attachment size (each) | 10 MB | `Attachment "<filename>" exceeds the 10 MB per-attachment limit` |
| Total attachment size | 20 MB | "Total attachment size exceeds the 20 MB limit" |

These are hard limits. The SDK returns `success: false` immediately without calling the API.

## Defensive practices

Since API rate limits are not published, design your integration to tolerate throttling and backpressure:

1. **Limit concurrency**: send emails sequentially or with a small concurrency pool (for example, 3-5 in parallel) rather than unbounded `Promise.all`.
2. **Back off on server errors**: if you receive HTTP 429 or 5xx responses, pause and retry with exponential backoff. The SDK does not retry automatically.
3. **Queue large batches**: use a job queue (Bull, Inngest, or a database-backed queue) instead of firing thousands of requests at once.
4. **Monitor status, not just success**: a `success: true` from `sendEmail` means the API accepted the message, not that it was delivered. Use `getEmailStatus` to track terminal outcomes.
5. **Contact BosonWare for volume**: if you plan to send more than a few thousand emails per month, reach out to [support@bosonware.com](mailto:support@bosonware.com) to discuss allowances and infrastructure.

## What the SDK does not enforce

The SDK does not implement:

* Per-second or per-minute rate limiting
* Automatic retries on 429 or 5xx
* Queueing or batching

These are application-level concerns. See [Production best practices](https://docs.bosonware.com/guides/production-best-practices.md) for patterns.

## Next steps

> [card] [Error codes](https://docs.bosonware.com/advanced/error-codes.md)
>
> Understand HTTP 429 and 5xx handling.

> [card] [Production best practices](https://docs.bosonware.com/guides/production-best-practices.md)
>
> Queues, retries, monitoring, and safe sending patterns.

> [card] [Request and response formats](https://docs.bosonware.com/advanced/request-response-formats.md)
>
> How the SDK parses responses and detects failures.

> [card] [Support](https://docs.bosonware.com/resources/support.md)
>
> Contact BosonWare for volume and allowance questions.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.