ERR_REQUIRE_ESM / Cannot use import statement outside a module
ERR_REQUIRE_ESM / Cannot use import statement outside a module
The package is ESM-only. CommonJS Or convert your project to ESM by adding
require() will fail.Fix: use dynamic import in CommonJS:"type": "module" to package.json.fetch / FormData / Blob / AbortController is not defined
fetch / FormData / Blob / AbortController is not defined
These globals are required by the SDK. They are native in Node.js 18+.Fix: upgrade to Node.js 18 or newer. The SDK has zero runtime dependencies and does not polyfill these APIs.
'apiKey' must be a non-empty string
'apiKey' must be a non-empty string
The constructor received an empty, missing, or whitespace-only API key.Causes and fixes:
- The environment variable is not loaded. Ensure
BOSONMAIL_API_KEYis set before the process starts. - In Next.js, do not use
NEXT_PUBLIC_BOSONMAIL_API_KEY. That prefix exposes the value to the browser bundle. Use a server-only variable instead. - In Cloudflare Workers, read the key from
c.env.BOSONMAIL_API_KEYinside the handler, not fromprocess.env.
Request timed out after 30000ms
Request timed out after 30000ms
The server did not respond within the configured timeout.Fix: the timeout message warns that the outcome may be unknown. Do not auto-retry blindly. Instead:
- If you have a
messageId, callgetEmailStatusto check whether the message was accepted. - If you do not have a
messageId, log the failure for manual review. - Only resend after confirming the previous attempt did not succeed, accepting the small risk of duplication.
Email must contain text or HTML content
Email must contain text or HTML content
The
body argument did not include a non-empty text or html field.Fix: provide at least one of the two. For best client compatibility, provide both.Invalid content for attachment
Invalid content for attachment
The attachment
content is not a Blob, ArrayBuffer, or Uint8Array.Common mistake: passing a string, a fs.ReadStream, or a base64 string directly.Fix: read the file into a Buffer first.Attachment exceeds size limits
Attachment exceeds size limits
Individual attachments are limited to 10 MB, and the total payload to 20 MB.Fix: compress files, split large payloads across multiple emails, or host large files externally and link to them in the HTML body.
sendEmail succeeded but the recipient never received the email
sendEmail succeeded but the recipient never received the email
A successful
sendEmail result means the API accepted the message. It does not mean the message was delivered.Fix:- Call
getEmailStatuswith themessageIdto track the delivery pipeline. - Ask the recipient to check spam or junk folders.
- Verify the recipient address is correct.
- If the status is
failed,bounced, orrejected, review the error details and correct the request.
messageId is undefined in the result
messageId is undefined in the result
The API response did not include a
messageId, emailId, or message_id field.Fix: this is rare but possible. You cannot look up status without a message ID. Log the id field if present, and contact support@bosonware.com with the timestamp and response details.getEmailStatus returns not_found
getEmailStatus returns not_found
The API could not locate an email for the provided message ID.Fix: confirm the message ID is correct and from the same account. Old messages may be purged. If the ID is recent and correct, contact support@bosonware.com.
getEmailStatus returns invalid_response
getEmailStatus returns invalid_response
The API response is missing required fields such as
id, status, or delivery_status.Fix: this indicates an unexpected API response shape. Report it to support@bosonware.com with the message ID, SDK version, and timestamp. Do not retry blindly.JSON send issues on SDK 0.2.0
JSON send issues on SDK 0.2.0
Version 0.2.0 sent
to, cc, and bcc as arrays in JSON requests. Version 0.2.1 fixed this to send comma-separated strings.Fix: upgrade to @bosonware-ent/bosonmail@0.2.1 or later.Content-Type manually set breaking multipart
Content-Type manually set breaking multipart
If you call the API directly and set
Content-Type: multipart/form-data manually without a boundary, the server cannot parse the body.Fix: let the HTTP client set the multipart header automatically. When using fetch with FormData, do not set Content-Type at all.Contacting support
When you open a support request, include:- SDK version (for example, 0.2.1)
- Runtime and version (Node.js 20, Bun 1.1, etc.)
statusCodeanderrorMessagefrom the resultmessageIdif available- Timestamp of the request (with timezone)
Next steps
Error codes
Complete catalog of every error code and message.
Security best practices
Prevent credential leaks and secure your integration.
Request and response formats
Understand how the SDK builds requests and parses responses.
Support
Reach BosonWare support with the details above.