Skip to main content
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.
The SDK is the recommended way to integrate. It handles serialization, validation, error mapping, and timeouts for you.

​
Base URL

You can override this in the SDK via the baseUrl option. See Client configuration for details.

​
Authentication

Every request must include an Authorization header with a Bearer token.
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.
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)

curl

​
Multipart request (with attachments)

curl

​
Request parameters

​
string
required
Primary recipient email address, or comma-separated addresses.
​
string
required
Email subject line. The SDK trims whitespace before sending.
​
string
Plain text body. Sent as textContent in multipart. Either text or html must be provided.
​
string
HTML body. Sent as htmlContent in multipart. Either text or html must be provided.
​
string
CC recipients as a comma-separated string. In JSON, joined with ”,”. In multipart, joined with ”, ”.
​
string
BCC recipients as a comma-separated string. Same joining rules as cc.
​
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.
​
boolean
required
Whether the request was accepted.
​
object
​
string | object
Error details when success is false. May be a plain string or an object with code and message.
​
string
Fallback error message when error is not present.
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 to confirm the canonical schema.

​
Get email status

Retrieve the current delivery status of a previously sent email.
curl
The messageId path parameter is URL-encoded by the SDK before the request is made.

​
Response envelope

​
boolean
required
Whether the status was retrieved.
​
object
​
string | object
Error details when success is false.
​
string
Error code, such as unauthorized or not_found.
​
string
Human-readable error description.
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 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.

​
Next steps

Client configuration

Override base URL, timeouts, and other SDK options.

Error codes

Full catalog of SDK and API error codes with fixes.

Request and response formats

Exact serialization rules for JSON and multipart requests.

Security best practices

Keep API keys and request data safe in production.