### Install lettersanitizer with npm or yarn

Source: https://github.com/mat-sz/lettersanitizer/blob/main/README.md

Install the lettersanitizer package using either npm or yarn. This is the first step before using the library.

```sh
npm install lettersanitizer
# or:
yarn install lettersanitizer
```

--------------------------------

### sanitize(html, text?, options?)

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

The main exported function. Accepts an HTML string, an optional plain-text fallback, and an options object. Processes HTML through a strict allowlist and returns a safe HTML string wrapped in a scoped `<div>`.

```APIDOC
## `sanitize(html, text?, options?)` — Core sanitization function

### Description
The main exported function. Accepts an HTML string, an optional plain-text fallback, and an options object. If `html` is empty but `text` is provided, the plain text is converted to escaped `<p>` elements. The sanitized result is returned as an HTML string, by default wrapped in a `<div>` with a unique or user-specified ID.

### Parameters
- **html** (string) - The raw HTML string to sanitize.
- **text** (string, optional) - A plain-text fallback if `html` is empty.
- **options** (object, optional) - Configuration options for sanitization.
  - **id** (string) - Sets the `id` of the wrapping `<div>` element. CSS selectors and element attributes are scoped with this ID.
  - **rewriteExternalLinks** (function(string): string, optional) - A callback invoked for every `href` attribute value on `<a>` elements. The return value of this callback is used as the new `href`.

### Request Example
```typescript
import { sanitize } from 'lettersanitizer';

// Basic usage: sanitize raw email HTML
const result = sanitize('<b>Hello</b><script>alert("xss")</script>', '', { id: 'email_001' });
// => '<div id="email_001"><b>Hello</b></div>'

// Plain-text fallback when no HTML is present
const textResult = sanitize('', 'Hello\nWorld', { id: 'email_002' });
// => '<div id="email_002"><p>Hello</p>\n<p>World</p></div>'

// Non-allowlisted tags are unwrapped (children preserved), allowlisted tags kept
const mixed = sanitize('<b>bold</b><unknown>plain</unknown>', '', { id: 'email_003' });
// => '<div id="email_003"><b>bold</b>plain</div>'

// Dangerous attributes are stripped
const xss = sanitize('<img onerror="alert(\'XSS\')" src="invalid:" />', '', { id: 'email_004' });
// => '<div id="email_004"><img></div>'
```

### Response
- **sanitizedHtml** (string) - The sanitized HTML string, wrapped in a `<div>`.
```

--------------------------------

### SanitizerOptions.rewriteExternalResources

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

A callback invoked for every src attribute on elements (e.g., <img>) and every url() value in inline or embedded CSS. Used to proxy or block remote resource loading. When set, schema restrictions are bypassed for resources.

```APIDOC
## SanitizerOptions.rewriteExternalResources

### Description
A callback invoked for every `src` attribute on elements (e.g., `<img>`) and every `url()` value in inline or embedded CSS. Used to proxy or block remote resource loading. When set, schema restrictions are bypassed for resources.

### Usage
```typescript
import { sanitize } from 'lettersanitizer';

const proxy = (url: string) => `https://imgproxy.example.com/?src=${encodeURIComponent(url)}`;

const result = sanitize(
  `<img src="https://tracker.example.com/pixel.png" />
   <span style="background: url('https://cdn.example.com/bg.jpg')">text</span>`,
  '',
  {
    id: 'msg_res',
    rewriteExternalResources: proxy,
  }
);
// Images and CSS backgrounds are proxied:
// <img src="https://imgproxy.example.com/?src=https%3A%2F%2Ftracker.example.com%2Fpixel.png">
// <span style="background: url(https://imgproxy.example.com/?src=https%3A%2F%2Fcdn.example.com%2Fbg.jpg);">text</span>
```
```

--------------------------------

### SanitizerOptions.allowedSchemas

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

An array of allowed URL schemes (protocols) for href and src attributes when no rewrite callbacks are set. Defaults to ['http', 'https', 'mailto']. Scheme matching is case-insensitive. URLs with disallowed schemes have their attribute removed entirely.

```APIDOC
## SanitizerOptions.allowedSchemas

### Description
An array of allowed URL schemes (protocols) for `href` and `src` attributes when no rewrite callbacks are set. Defaults to `['http', 'https', 'mailto']`. Scheme matching is case-insensitive. URLs with disallowed schemes have their attribute removed entirely.

### Usage
```typescript
import { sanitize } from 'lettersanitizer';

// Default schemas: http, https, mailto are allowed
const safe = sanitize('<a href="mailto:user@example.com">Email us</a>', '', { id: 'test' });
// => '<div id="test"><a href="mailto:user@example.com" rel="noopener noreferrer" target="_blank">Email us</a></div>'

// ftp:// is not in the default list — href is stripped
const ftpBlocked = sanitize('<a href="ftp://files.example.com">FTP</a>', '', { id: 'test' });
// => '<div id="test"><a rel="noopener noreferrer" target="_blank">FTP</a></div>'

// Allow data: URIs for inline images (e.g., in offline/embedded email viewers)
const withData = sanitize(
  '<img src="data:image/png;base64,iVBORw0KGgo=" />',
  '',
  { id: 'test', allowedSchemas: ['http', 'https', 'mailto', 'data'] }
);
// => '<div id="test"><img src="data:image/png;base64,iVBORw0KGgo="></div>'
```
```

--------------------------------

### CSS Scoping and Media Rule Handling

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Demonstrates how Lettersanitizer automatically scopes embedded `<style>` rules to a wrapper ID and preserves `@media` rules while stripping other at-rules like `@keyframes` and `@font-face`.

```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  `<style>
    body { background: white; }
    .header { font-size: 24px; }
    #logo { width: 100px; }
    @media (max-width: 600px) { .header { font-size: 16px; } }
    @keyframes spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }
    @font-face { font-family: "Custom"; src: url("/font.woff2"); }
    @import url('external.css');
  </style>
  <div class="header" id="logo">Hello</div>`,
  '',
  { id: 'email' }
);
// @keyframes, @font-face, @import are removed
// body selector → #email body, .header → #email .email_header, #logo → #email #email_logo
// @media block is preserved and scoped
// => '<div id="email"><div class="email_header" id="email_logo">Hello</div><style>#email body {background: white;}
#email .email_header {font-size: 24px;}
#email #email_logo {width: 100px;}
@media (max-width: 600px) {#email .email_header {font-size: 16px;}}</style></div>'
```

--------------------------------

### Customizing Allowed CSS Properties

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Extend the default allowlist of CSS properties to include custom ones. Ensure that only the specified properties are retained in inline styles and `<style>` blocks.

```typescript
import { sanitize, allowedCssProperties } from 'lettersanitizer';

// Use the default allowlist plus a custom addition
const result = sanitize(
  '<span style="color: red; pointer-events: all; font-size: 14px;">text</span>',
  '',
  {
    id: 'msg',
    allowedCssProperties: [...allowedCssProperties, 'pointer-events'],
  }
);
// 'pointer-events' is now allowed; 'color' and 'font-size' are already in the default list
// => '<div id="msg"><span style="color: red; pointer-events: all; font-size: 14px;">text</span></div>'
```

```typescript
// Restrict to a minimal set (e.g., text-only rendering)
const minimal = sanitize(
  '<p style="color: blue; margin: 10px; animation: spin 1s;">Hello</p>',
  '',
  { id: 'msg2', allowedCssProperties: ['color', 'font-size', 'font-weight'] }
);
// Only 'color' survives; 'margin' and 'animation' are stripped
// => '<div id="msg2"><p style="color: blue;">Hello</p></div>'
```

--------------------------------

### Rewrite External Resources with a Callback

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Use `rewriteExternalResources` to proxy or block remote resource loading. This callback is invoked for `src` attributes and CSS `url()` values, bypassing schema restrictions.

```typescript
import { sanitize } from 'lettersanitizer';

const proxy = (url: string) => `https://imgproxy.example.com/?src=${encodeURIComponent(url)}`;

const result = sanitize(
  `<img src="https://tracker.example.com/pixel.png" />
   <span style="background: url('https://cdn.example.com/bg.jpg')">text</span>`,
  '',
  {
    id: 'msg_res',
    rewriteExternalResources: proxy,
  }
);
// Images and CSS backgrounds are proxied:
// <img src="https://imgproxy.example.com/?src=https%3A%2F%2Ftracker.example.com%2Fpixel.png">
// <span style="background: url(https://imgproxy.example.example.com/?src=https%3A%2F%2Fcdn.example.com%2Fbg.jpg);">text</span>
```

--------------------------------

### Basic Sanitization with Lettersanitizer

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Sanitize raw email HTML using the `sanitize` function. Dangerous tags like `<script>` are removed, and non-allowlisted tags are unwrapped. Plain text fallbacks can be provided.

```typescript
import { sanitize } from 'lettersanitizer';

// Basic usage: sanitize raw email HTML
const result = sanitize('<b>Hello</b><script>alert("xss")</script>', '', { id: 'email_001' });
// => '<div id="email_001"><b>Hello</b></div>'

// Plain-text fallback when no HTML is present
const textResult = sanitize('', 'Hello\nWorld', { id: 'email_002' });
// => '<div id="email_002"><p>Hello</p>\n<p>World</p></div>'

// Non-allowlisted tags are unwrapped (children preserved), allowlisted tags kept
const mixed = sanitize('<b>bold</b><unknown>plain</unknown>', '', { id: 'email_003' });
// => '<div id="email_003"><b>bold</b>plain</div>'

// Dangerous attributes are stripped
const xss = sanitize('<img onerror="alert(\'XSS\')" src="invalid:" />', '', { id: 'email_004' });
// => '<div id="email_004"><img></div>'
```

--------------------------------

### Rewriting External Links with SanitizerOptions.rewriteExternalLinks

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Provide a callback to `rewriteExternalLinks` to customize `href` attributes on `<a>` elements. This bypasses schema restrictions, and the callback's return value becomes the new `href`. All `<a>` tags also receive `rel="noopener noreferrer"` and `target="_blank"`.

```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  '<a href="https://example.com/track?id=42">Click here</a>',
  '',
  {
    id: 'msg_links',
    rewriteExternalLinks: (url) => `https://myproxy.example.com/redirect?to=${encodeURIComponent(url)}`,
  }
);
// => '<div id="msg_links"><a href="https://myproxy.example.com/redirect?to=https%3A%2F%2Fexample.com%2Ftrack%3Fid%3D42" rel="noopener noreferrer" target="_blank">Click here</a></div>'

// Relative URLs are also rewritten when the callback is set
const relative = sanitize('<a href="./newsletter">Read more</a>', '', {
  id: 'msg_rel',
  rewriteExternalLinks: (url) => './redirect?url=' + url,
});
// => '<div id="msg_rel"><a href="./redirect?url=./newsletter" rel="noopener noreferrer" target="_blank">Read more</a></div>'
```

--------------------------------

### Basic HTML Sanitization with lettersanitizer

Source: https://github.com/mat-sz/lettersanitizer/blob/main/README.md

Use the sanitize function to clean HTML content. It removes potentially harmful tags like script and wraps the output in a div with a specified ID. Ensure 'sanitize' is imported from 'lettersanitizer'.

```ts
import { sanitize } from 'lettersanitizer';

sanitize('<b>test</b><script>test</script>', '', { id: 'test' });
// <div id="test"><b>test</b></div>
```

--------------------------------

### Configure Allowed URL Schemes

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Specify `allowedSchemas` to control which URL protocols are permitted in `href` and `src` attributes. URLs with disallowed schemes will have their attributes removed.

```typescript
import { sanitize } from 'lettersanitizer';

// Default schemas: http, https, mailto are allowed
const safe = sanitize('<a href="mailto:user@example.com">Email us</a>', '', { id: 'test' });
// => '<div id="test"><a href="mailto:user@example.com" rel="noopener noreferrer" target="_blank">Email us</a></div>'

// ftp:// is not in the default list — href is stripped
const ftpBlocked = sanitize('<a href="ftp://files.example.com">FTP</a>', '', { id: 'test' });
// => '<div id="test"><a rel="noopener noreferrer" target="_blank">FTP</a></div>'

// Allow data: URIs for inline images (e.g., in offline/embedded email viewers)
const withData = sanitize(
  '<img src="data:image/png;base64,iVBORw0KGgo=" />',
  '',
  { id: 'test', allowedSchemas: ['http', 'https', 'mailto', 'data'] }
);
// => '<div id="test"><img src="data:image/png;base64,iVBORw0KGgo="></div>'
```

--------------------------------

### SanitizerOptions Interface for lettersanitizer

Source: https://github.com/mat-sz/lettersanitizer/blob/main/README.md

Defines the available options for the sanitize function, including ID, tag dropping, URL rewriting, allowed schemas, CSS priority preservation, and wrapper behavior. These options allow fine-grained control over the sanitization process.

```ts
interface SanitizerOptions {
  id?: string;
  dropAllHtmlTags?: boolean;
  rewriteExternalResources?: (url: string) => string;
  rewriteExternalLinks?: (url: string) => string;
  allowedSchemas?: string[];
  preserveCssPriority?: boolean;
  noWrapper?: boolean;
}

function sanitize(html: string, text?: string, options?: SanitizerOptions);
```

--------------------------------

### SanitizerOptions.noWrapper

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

When true, the sanitized content is returned without the wrapping <div id="..."> element. CSS scoping (ID/class prefixing) is also disabled. Useful when the caller manages its own container element.

```APIDOC
## SanitizerOptions.noWrapper

### Description
When `true`, the sanitized content is returned without the wrapping `<div id="...">` element. CSS scoping (ID/class prefixing) is also disabled. Useful when the caller manages its own container element.

### Usage
```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  '<p class="greeting">Hello!</p><style>.greeting { color: green; }</style>',
  '',
  { noWrapper: true }
);
// Class names and CSS selectors are NOT prefixed:
// => '<p class="greeting">Hello!</p><style>.greeting {color: green;}</style>'

// Compare: with wrapper and id, classes are prefixed
const wrapped = sanitize(
  '<p class="greeting">Hello!</p><style>.greeting { color: green; }</style>',
  '',
  { id: 'msg' }
);
// => '<div id="msg"><p class="msg_greeting">Hello!</p><style>#msg .msg_greeting {color: green;}</style></div>'
```
```

--------------------------------

### Exported Default CSS Property Allowlist

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Access the default list of allowed CSS properties for inspection or extension. This list can be used as a base for creating custom allowlists.

```typescript
import { allowedCssProperties } from 'lettersanitizer';

console.log(allowedCssProperties.includes('color'));        // true
console.log(allowedCssProperties.includes('pointer-events')); // false
console.log(allowedCssProperties.length);                   // ~130 properties

// Use as a base to build a custom allowlist
const myAllowedProperties = [...allowedCssProperties, 'pointer-events', 'cursor'];
```

--------------------------------

### SanitizerOptions.dropAllHtmlTags

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

When true, all HTML tags are removed and only their text content is preserved. <style> blocks are also removed. Useful for rendering a plain-text view of email content with no markup.

```APIDOC
## SanitizerOptions.dropAllHtmlTags

### Description
When `true`, all HTML tags are removed and only their text content is preserved. `<style>` blocks are also removed. Useful for rendering a plain-text view of email content with no markup.

### Usage
```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  '<h1>Hello <b>World</b></h1><p>This is <em>important</em></p><script>alert("bad")</script>',
  '',
  { id: 'plain', dropAllHtmlTags: true }
);
// => '<div id="plain">Hello WorldThis is important</div>'
```
```

--------------------------------

### CSS Scoping with SanitizerOptions.id

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Use the `id` option to set the ID of the wrapping `<div>` element. This scopes CSS selectors and element attributes to prevent style leakage into the host page.

```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  `<style>.title { color: red; } #header { font-size: 20px; }</style>
   <h1 class="title" id="header">Welcome</h1>`,
  '',
  { id: 'msg_123' }
);
// CSS selectors and element attributes are scoped:
// => '<div id="msg_123"><style>#msg_123 .msg_123_title {color: red;} #msg_123 #msg_123_header {font-size: 20px;}</style><h1 class="msg_123_title" id="msg_123_header">Welcome</h1></div>'
```

--------------------------------

### SanitizerOptions.preserveCssPriority

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Controls whether !important declarations are preserved in sanitized CSS. Defaults to true. Set to false to strip all !important flags, useful when the host page's styles should be able to override email styles.

```APIDOC
## SanitizerOptions.preserveCssPriority

### Description
Controls whether `!important` declarations are preserved in sanitized CSS. Defaults to `true`. Set to `false` to strip all `!important` flags, useful when the host page's styles should be able to override email styles.

### Usage
```typescript
import { sanitize } from 'lettersanitizer';

// Default: !important is preserved
const preserved = sanitize(
  '<style>p { color: red !important; }</style><p>text</p>',
  '',
  { noWrapper: true }
);
// => '<p>text</p><style>p {color: red !important;}</style>'

// Stripped: !important removed
const stripped = sanitize(
  '<style>p { color: red !important; }</style><p>text</p>',
  '',
  { noWrapper: true, preserveCssPriority: false }
);
// => '<p>text</p><style>p {color: red;}</style>'
```
```

--------------------------------

### Strip All HTML Tags

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Set `dropAllHtmlTags` to `true` to remove all HTML tags and preserve only the text content. This is useful for rendering plain-text views.

```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  '<h1>Hello <b>World</b></h1><p>This is <em>important</em></p><script>alert("bad")</script>',
  '',
  { id: 'plain', dropAllHtmlTags: true }
);
// => '<div id="plain">Hello WorldThis is important</div>'
```

--------------------------------

### sanitize function

Source: https://github.com/mat-sz/lettersanitizer/blob/main/README.md

The sanitize function uses DOMParser to sanitize HTML content and returns safe HTML text. It accepts the HTML string, fallback text, and an optional options object.

```APIDOC
## sanitize function

### Description
Sanitizes HTML content using DOMParser and returns safe HTML text. `text` is used for fallback if no HTML source is available.

### Signature
```typescript
function sanitize(html: string, text?: string, options?: SanitizerOptions)
```

### Parameters
#### `html` (string) - Required
The HTML content to sanitize.

#### `text` (string) - Optional
Fallback text to use if no HTML source is available.

#### `options` (SanitizerOptions) - Optional
An object containing sanitization options.

```typescript
interface SanitizerOptions {
  id?: string;
  dropAllHtmlTags?: boolean;
  rewriteExternalResources?: (url: string) => string;
  rewriteExternalLinks?: (url: string) => string;
  allowedSchemas?: string[];
  preserveCssPriority?: boolean;
  noWrapper?: boolean;
}
```

### Request Example
```typescript
import { sanitize } from 'lettersanitizer';

sanitize('<b>test</b><script>test</script>', '', { id: 'test' });
// Expected output: <div id="test"><b>test</b></div>
```

### Response
Returns the sanitized HTML string.
```

--------------------------------

### Remove Outer Wrapper Element

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

Use `noWrapper: true` to return sanitized content without the default wrapping `<div>` element. CSS scoping is also disabled.

```typescript
import { sanitize } from 'lettersanitizer';

const result = sanitize(
  '<p class="greeting">Hello!</p><style>.greeting { color: green; }</style>',
  '',
  { noWrapper: true }
);
// Class names and CSS selectors are NOT prefixed:
// => '<p class="greeting">Hello!</p><style>.greeting {color: green;}</style>'

// Compare: with wrapper and id, classes are prefixed
const wrapped = sanitize(
  '<p class="greeting">Hello!</p><style>.greeting { color: green; }</style>',
  '',
  { id: 'msg' }
);
// => '<div id="msg"><p class="msg_greeting">Hello!</p><style>#msg .msg_greeting {color: green;}</style></div>'
```

--------------------------------

### Control CSS !important Declarations

Source: https://context7.com/mat-sz/lettersanitizer/llms.txt

The `preserveCssPriority` option controls whether `!important` declarations are kept in sanitized CSS. Defaults to `true`.

```typescript
import { sanitize } from 'lettersanitizer';

// Default: !important is preserved
const preserved = sanitize(
  '<style>p { color: red !important; }</style><p>text</p>',
  '',
  { noWrapper: true }
);
// => '<p>text</p><style>p {color: red !important;}</style>'

// Stripped: !important removed
const stripped = sanitize(
  '<style>p { color: red !important; }</style><p>text</p>',
  '',
  { noWrapper: true, preserveCssPriority: false }
);
// => '<p>text</p><style>p {color: red;}</style>'
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.