Skip to main content
The BosonMail SDK authenticates every request with a Bearer token sent in the Authorization header. You provide the token as apiKey when constructing the client. The SDK handles headers automatically; you never set them manually.

​
Provide your API key

Pass the key directly to the constructor, typically from an environment variable.
lib/bosonmail.ts
The SDK stores the key on the readonly apiKey property. Avoid logging the client object because it contains the key.

​
Constructor validation

The constructor validates the apiKey immediately and throws if it is missing or invalid:
  • Empty or whitespace-only string: Error("'apiKey' must be a non-empty string")
This is the only place the SDK throws. All method failures return { success: false } objects instead of rejecting.

​
API key scopes

Scopes determine the actions a token can perform:
  • email:read: allows calling getEmailStatus.
  • email:send: allows sending emails via sendEmail and also calling getEmailStatus:requires either email:read or email:send.
  • sendEmail: Requires email:send.

​
What happens with an invalid key

If the API rejects the key, the SDK returns a typed failure object rather than throwing:
  • sendEmail returns { success: false, statusCode: <HTTP status>, errorMessage: <message> }
  • getEmailStatus returns { success: false, errorCode: "unauthorized", errorMessage: <message>, statusCode: <HTTP status> }

​
Raw HTTP example

If you are debugging or writing a non-Node client, the header format is:
curl

​
Server-only warning

Never expose your BosonMail API key in browser code, frontend environment variables, or client-side bundles. The key grants access to your email account. Always call the SDK from a server, API route, or serverless function.
Recommended practices:
  • Store the key in a secrets manager or encrypted environment variable
  • Do not commit .env files containing the key
  • Do not log the client object or the key itself
  • Rotate keys periodically if BosonWare supports it

​
Next steps

Configuration

Set base URLs, timeouts, and per-environment client instances.

API keys

Key management, rotation, and access control.

Security

Secrets handling, credential hygiene, and safe deployment.

Quickstart

Send your first authenticated email.