> ## 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.

# What is BosonMail?

> Overview of BosonMail, the managed business email platform by BosonWare Enterprises, and how the official SDK fits into your application.

BosonMail is a managed business email platform built by BosonWare Enterprises (Kenya) for teams that need reliable, professional email without operating their own mail infrastructure. It is priced per inbox, billed in Kenyan Shillings via M-PESA, and includes storage, outbound allowances, and internal messaging.

The BosonMail SDK is the official Node.js and TypeScript client for the BosonMail REST API. It gives you a typed, promise-based interface for sending transactional email and checking delivery status from your backend.

## How it works

Your application calls the SDK, the SDK calls the BosonMail API over HTTPS, and BosonMail routes the message to the recipient's mail servers.

```mermaid theme={null}
flowchart LR
    A[Your server] --> B[BosonMail SDK]
    B --> C[BosonMail API]
    C --> D[Recipient mail servers]
```

The SDK uses two endpoints:

* `POST /emails/send` to submit a message
* `GET /emails/:id/status` to look up its current state

> [!NOTE]
>
> The SDK source code calls `POST /emails/send`. The README lists `POST /mail/send`, which is pending confirmation by BosonWare. The code is authoritative.

## BosonMail platform facts

| Feature | Detail |
| - | - |
| Pricing | KSh 100 per inbox per month (yearly), or KSh 150 monthly |
| Storage | 5 GB per inbox |
| Outbound | 500 emails per inbox per month |
| Inbound | Unlimited |
| Internal | Free unlimited email between inboxes in the same account |
| Extra outbound | KSh 150 per 1,000 email credits (valid 90 days), or KSh 100 per 1,000 emails per month added to an inbox |
| Billing | M-PESA |
| Webmail | [https://webmail.bosonware.com](https://webmail.bosonware.com) |
| Sign up | [https://identity.bosonware.com/login](https://identity.bosonware.com/login) |

> [!WARNING]
>
> It is not confirmed whether emails sent through the SDK and API count against the 500 outbound emails per inbox per month. Contact [support@bosonware.com](mailto:support@bosonware.com) to confirm.

## Key concepts

### Submission vs delivery

When you call `sendEmail`, the SDK returns as soon as BosonMail accepts the message. The returned `status` is typically `"queued"`. Delivery to the recipient's inbox is a separate, asynchronous step. Use `getEmailStatus` to poll or audit the outcome later.

### Content types

You can send plain text, HTML, or both. Providing both improves compatibility across email clients. The SDK validates that at least one of `text` or `html` is present before making a request.

### Recipients

The SDK supports `to`, `cc`, and `bcc` fields. Each accepts a single email address or an array of addresses. The SDK joins arrays into comma-separated strings before sending them to the API.

### Attachments

Files are sent as `multipart/form-data`. The SDK validates per-file size (10 MB max), total size (20 MB max), and file count (10 max) on the client side before uploading.

## What the SDK does not do

The SDK is intentionally minimal. It does not provide:

* Automatic retries or backoff
* Polling loops for status updates
* Webhooks for delivery events
* Email templates or templating engines
* A `from` or `reply-to` parameter (the sender address is determined by the API key's associated inbox or account)
* Batch or bulk send endpoints
* Scheduling or delayed sends
* Idempotency keys

If you need retries, polling, or templating, you build that logic in your own application code.


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