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

# API reference

> REST API endpoints used by the BosonMail SDK: send emails and check delivery status. Includes curl examples and request/response envelopes.

The BosonMail SDK communicates with BosonWare's REST API at `https://webmail.bosonware.com/api/v1`. This page documents the endpoints the SDK calls so you can build custom integrations, debug requests, or call the API directly when the SDK is not available.

> [!NOTE]
>
> The SDK is the recommended way to integrate. It handles serialization, validation, error mapping, and timeouts for you.

## Base URL

```text theme={null}
https://webmail.bosonware.com/api/v1
```

You can override this in the SDK via the `baseUrl` option. See [Client configuration](https://docs.bosonware.com/sdk/client-configuration.md) for details.

## Authentication

Every request must include an `Authorization` header with a Bearer token.

```text theme={null}
Authorization: Bearer your_api_key
```

> [!WARNING]
>
> Do not expose API keys in client-side code or public repositories. Store keys in environment variables or a secrets manager.

## Send an email

Submit an email for delivery. The API accepts JSON when there are no attachments, and `multipart/form-data` when files are included.

> [!NOTE]
>
> The SDK source code calls `POST /emails/send`. The README lists `POST /mail/send`. The `/emails/send` path is what the published SDK actually uses; the `/mail/send` path is pending confirmation by BosonWare.

### JSON request (no attachments)

```bash curl theme={null}
 curl --request POST \
   --url https://webmail.bosonware.com/api/v1/emails/send \
   --header 'Authorization: Bearer your_api_key' \
   --header 'Content-Type: application/json' \
   --data '{
     "to": "customer@example.com",
     "cc": "cc@example.com,another@example.com",
     "bcc": "bcc@example.com",
     "subject": "Welcome to BosonMail",
     "text": "Hello and welcome!",
     "html": "<p>Hello and welcome!</p>"
   }'
```

### Multipart request (with attachments)

```bash curl theme={null}
 curl --request POST \
   --url https://webmail.bosonware.com/api/v1/emails/send \
   --header 'Authorization: Bearer your_api_key' \
   --form 'to="customer@example.com"' \
   --form 'subject="Welcome to BosonMail"' \
   --form 'textContent="Hello and welcome!"' \
   --form 'htmlContent="<p>Hello and welcome!</p>"' \
   --form 'cc="cc@example.com, another@example.com"' \
   --form 'bcc="bcc@example.com"' \
   --form 'attachments=@invoice.pdf;type=application/pdf'
```

### Request parameters

**to** `string` *required*

Primary recipient email address, or comma-separated addresses.

**subject** `string` *required*

Email subject line. The SDK trims whitespace before sending.

**text** `string`

Plain text body. Sent as `textContent` in multipart. Either `text` or `html` must be provided.

**html** `string`

HTML body. Sent as `htmlContent` in multipart. Either `text` or `html` must be provided.

**cc** `string`

CC recipients as a comma-separated string. In JSON, joined with ",". In multipart, joined with ", ".

**bcc** `string`

BCC recipients as a comma-separated string. Same joining rules as `cc`.

**attachments** `file[]`

One or more file attachments. Only accepted in multipart requests. Maximum 10 files, 10 MB each, 20 MB total.

### Response envelope

The API returns a JSON envelope. The SDK expects `success: true` and a `data` object on success.

**success** `boolean` *required*

Whether the request was accepted.

**data** `object`

**properties**

**id** `string`

Internal record identifier.

**messageId** `string`

Unique message identifier for status lookups. May also be returned as `emailId` or `message_id`.

**status** `string`

Initial status, typically `"queued"`. The SDK defaults to `"queued"` when the API omits it.

**error** `string | object`

Error details when `success` is `false`. May be a plain string or an object with `code` and `message`.

**message** `string`

Fallback error message when `error` is not present.

> [!NOTE]
>
> The exact server schema has not been published by BosonWare. The fields above are derived from the SDK's parsing logic. Contact [support@bosonware.com](mailto:support@bosonware.com) to confirm the canonical schema.

## Get email status

Retrieve the current delivery status of a previously sent email.

```bash curl theme={null}
 curl --request GET \
   --url 'https://webmail.bosonware.com/api/v1/emails/MSG_abc123/status' \
   --header 'Authorization: Bearer your_api_key' \
   --header 'Accept: application/json'
```

The `messageId` path parameter is URL-encoded by the SDK before the request is made.

### Response envelope

**success** `boolean` *required*

Whether the status was retrieved.

**data** `object`

**properties**

**id** `string | number` *required*

Internal record identifier.

**uuid** `string`

UUID for the email record.

**message\_id** `string`

Message identifier matching the path parameter.

**status** `string` *required*

Current processing status.

**delivery\_status** `string` *required*

Delivery status reported by the mail infrastructure.

**recipient** `string | string[]`

Recipient address or addresses.

**subject** `string`

Email subject.

**created\_at** `string`

ISO 8601 timestamp when the email was created.

**error** `string | object`

Error details when `success` is `false`.

**code** `string`

Error code, such as `unauthorized` or `not_found`.

**message** `string`

Human-readable error description.

> [!NOTE]
>
> The exact server schema has not been published by BosonWare. The fields above are derived from the SDK's parsing logic. Contact [support@bosonware.com](mailto:support@bosonware.com) to confirm the canonical schema.

## Error handling

The SDK treats a response as failed when any of the following is true:

* The HTTP status is not OK (`!response.ok`).
* The parsed body is not an object.
* The body's `success` field is not `true`.

When the API returns no usable error details, the SDK falls back to `Request failed (HTTP <status> <statusText>)`.

For a complete catalog of error codes and messages, see [Error codes](https://docs.bosonware.com/advanced/error-codes.md).

## Next steps

> [card] [Client configuration](https://docs.bosonware.com/sdk/client-configuration.md)
>
> Override base URL, timeouts, and other SDK options.

> [card] [Error codes](https://docs.bosonware.com/advanced/error-codes.md)
>
> Full catalog of SDK and API error codes with fixes.

> [card] [Request and response formats](https://docs.bosonware.com/advanced/request-response-formats.md)
>
> Exact serialization rules for JSON and multipart requests.

> [card] [Security best practices](https://docs.bosonware.com/advanced/security.md)
>
> Keep API keys and request data safe in production.


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