Skip to Content
Brandedmail 1.0 release 🎉
Responses & Errors

Responses & Errors

This page summarizes the responses you get back from Brandedmail and the common errors you might see when sending emails.

Successful responses

You can send prebuilt templates (like welcome, trial-ending, reset-password, etc.) or your own custom HTML, and both paths behave the same from a responses/errors point of view.

  • Templates use endpoints/methods like sendTemplate and POST /emails.
  • Custom HTML uses sendHtml and POST /emails/html.

For both template and HTML sends, a successful response from the API looks like:

{
  "message": "Email Sent Successfully"
}

The HTTP status code is 200 OK for both /emails (templates) and /emails/html (custom HTML).

When using the Node SDK, both sendTemplate (templates) and sendHtml (your own HTML) resolve to this same response body and status.

SDK error classes

The Node SDK throws specific error classes you can catch. These map closely to the HTTP status codes from the API:

  • BrandedMailValidationError – your payload is invalid (missing fields, wrong types, invalid email addresses, etc.). Maps to 400 Bad Request.
  • BrandedMailAuthenticationError – your API key is missing or invalid. Maps to 401 Unauthorized.
  • BrandedMailForbiddenError – you’re not allowed to perform this action, for example:
    • sender domain not found or not verified,
    • brand not accessible for this user,
    • plan/usage limits reached.
      Maps to 403 Forbidden.
  • BrandedMailNotFoundError – resource not found (for example, brand or route). Maps to 404 Not Found.
  • BrandedMailServerError – server‑side failure while sending/logging the email (SES failure, internal error, etc.). Maps to 5xx status codes.
  • BrandedMailConfigError – local configuration issues (for example, misconfigured SDK).
  • BrandedMailError – base class for all Brandedmail SDK errors; used for generic/unknown errors.

Example error handling (Node)

import Brandedmail, {
  BrandedMailValidationError,
  BrandedMailAuthenticationError,
  BrandedMailForbiddenError,
  BrandedMailNotFoundError,
  BrandedMailServerError,
  BrandedMailError,
} from "@brandedmail/node";
 
const client = new Brandedmail(process.env.BRANDEDMAIL_API_KEY!);
 
try {
  await client.sendTemplate(/* ... */);
} catch (error) {
  if (error instanceof BrandedMailAuthenticationError) {
    // Handle invalid/missing API key
  } else if (error instanceof BrandedMailValidationError) {
    // Handle invalid payload (check error.data for details)
  } else if (error instanceof BrandedMailForbiddenError) {
    // Handle forbidden: domain not verified, brand not accessible, quota/plan issues, etc.
  } else if (error instanceof BrandedMailNotFoundError) {
    // Handle missing resources
  } else if (error instanceof BrandedMailServerError) {
    // Handle server-side failure (retry later, log, alert, etc.)
  } else if (error instanceof BrandedMailError) {
    // Generic Brandedmail error (network/unknown/etc.)
  } else {
    // Non-Brandedmail error
  }
}

Common HTTP status codes

When calling the HTTP API directly, you’ll see standard HTTP status codes:

  • 200 / 201 – email accepted and queued for delivery.
  • 400 – bad request (validation error: missing/invalid fields, invalid emails, wrong template data shape, etc.).
  • 401 – authentication error (missing/invalid API key).
  • 403 – forbidden:
    • sender domain not found or not verified,
    • brand not accessible for this user,
    • plan/usage limits reached.
  • 404 – not found (route or resource).
  • 500 – internal server error (unexpected failure while sending or logging the email).

Example failed HTTP response

{
  "statusCode": 403,
  "message": "Sender domain is not verified. Please verify it first.",
  "error": "Forbidden"
}

If you use the SDK, these HTTP errors are translated into the corresponding SDK error classes described above.

Getting StartedTemplates