HTML emails

The BosonMail SDK supports HTML email content through the html field in SendEmailBody. You can send HTML-only, text-only, or both together. When you provide both, the API can present a multipart alternative that improves compatibility across email clients.

The html field

string

HTML content for the email body. Must be a non-empty string after trimming. Either text or html (or both) is required.

const result = await client.sendEmail(
  "customer@example.com",
  "Welcome to our platform",
  {
    html: "<h1>Welcome</h1><p>Thanks for signing up.</p>"
  }
);

Why include both text and HTML

Email clients handle HTML differently. Some strip styles, others block external images, and a minority still prefer plain text. Providing both text and html gives the receiving server and client the option to display the most appropriate version.

const result = await client.sendEmail(
  "customer@example.com",
  "Your weekly summary",
  {
    text: "Your weekly summary is ready. Open the link below to view it.",
    html: "<h1>Your weekly summary</h1><p><a href=\"https://example.com/summary\">View summary</a></p>"
  }
);

The SDK sends both fields to the API when you provide them. It does not generate a text fallback from HTML automatically. Write the text version yourself for the best results.

Validation

The SDK enforces two rules for content fields:

If text or html is present, it must be a string: 'text' and 'html' must be strings
At least one must be non-empty after trimming: Email must contain text or HTML content

Practical HTML tips

Inline styles over external CSS

Most email clients ignore <style> blocks in the <head>. Use inline style attributes for reliable rendering.

<!-- Good -->
<p style="color: #333; font-size: 16px; line-height: 1.5;">
  Your content here.
</p>

<!-- Less reliable -->
<style>
  p { color: #333; }
</style>

Tables for layout

CSS Grid and Flexbox have limited support in email clients. Use HTML tables for complex layouts.

<table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr>
    <td style="padding: 20px;">
      <h1 style="margin: 0;">Order confirmed</h1>
    </td>
  </tr>
</table>

Absolute image URLs

Always use full https:// URLs for images. Relative paths and CID references are not supported by the SDK.

<img src="https://cdn.example.com/logo.png" alt="Company logo" width="120" />

Escape user input to prevent HTML injection

If you interpolate user-provided data into HTML, escape it first. A simple helper:

lib/escape-html.ts

function escapeHtml(input: string): string {
  return input
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

// Usage
const userName = escapeHtml(userInput.name);
const html = `<p>Hello ${userName}, your order is ready.</p>`;

Never pass raw user input into HTML without escaping or sanitization. This prevents XSS-like injection in email clients that render HTML.

Full example

send-html.ts

import BosonMailClient from "@bosonware-ent/bosonmail";

function escapeHtml(input: string): string {
  return input
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#39;");
}

const client = new BosonMailClient({ apiKey: process.env.BOSONMAIL_API_KEY! });

const userName = "Alice";
const orderId = "ORD-12345";

const result = await client.sendEmail(
  "customer@example.com",
  `Order ${orderId} confirmed`,
  {
    text: `Hi ${userName}, your order ${orderId} has been confirmed.`,
    html: `
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr><td style="padding: 24px; font-family: sans-serif;">
          <h1 style="color: #1a1a1a;">Order confirmed</h1>
          <p>Hi ${escapeHtml(userName)},</p>
          <p>Your order <strong>${escapeHtml(orderId)}</strong> has been confirmed.</p>
        </td></tr>
      </table>
    `
  }
);

Sending emails

Full sendEmail reference with parameters and validation rules.

Attachments

How to attach files to HTML and text emails.

Guides: HTML emails

Step-by-step guide for building rich email templates.

Error handling

How to handle validation and API errors.

Getting Started

SDK Reference

Guides

Advanced

Resources

The html field

Why include both text and HTML

Validation

Practical HTML tips

Inline styles over external CSS

Tables for layout

Absolute image URLs

Escape user input to prevent HTML injection

Full example

Sending emails

Attachments

Guides: HTML emails

Error handling

​The html field

​Why include both text and HTML

​Validation

​Practical HTML tips

​Inline styles over external CSS

​Tables for layout

​Absolute image URLs

​Escape user input to prevent HTML injection

​Full example

Sending emails

Attachments

Guides: HTML emails

Error handling

The html field

Why include both text and HTML

Validation

Practical HTML tips

Inline styles over external CSS

Tables for layout

Absolute image URLs

Escape user input to prevent HTML injection

Full example