> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bosonware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HTML emails

> How to send HTML emails with the BosonMail SDK, why you should include a text alternative, and practical tips for email-client compatibility.

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

**html** `string`

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

```typescript theme={null}
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.

```typescript theme={null}
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>"
  }
);
```

> [!TIP]
>
> 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:

1. If `text` or `html` is present, it must be a string: `'text' and 'html' must be strings`
2. 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.

```html theme={null}
<!-- 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.

```html theme={null}
<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.

```html theme={null}
<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:

```typescript lib/escape-html.ts theme={null}
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>`;
```

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

## Full example

```typescript send-html.ts theme={null}
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>
    `
  }
);
```

> [card] [Sending emails](https://docs.bosonware.com/sdk/sending-emails.md)
>
> Full sendEmail reference with parameters and validation rules.

> [card] [Attachments](https://docs.bosonware.com/sdk/attachments.md)
>
> How to attach files to HTML and text emails.

> [card] [Guides: HTML emails](https://docs.bosonware.com/guides/html-emails.md)
>
> Step-by-step guide for building rich email templates.

> [card] [Error handling](https://docs.bosonware.com/sdk/error-handling.md)
>
> How to handle validation and API errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.