HTML Sanitizer

Coerces externally-sourced rich-text HTML — a paste from Word or Google Docs, an import, a migration — into the tag set the Speakap rich-text schema allows.

Unlike validation, it never rejects. Anything unsupported is rewritten into the nearest allowed shape, or dropped; the surrounding text always survives. Run a paste through this endpoint before sending it as htmlBody, and content that would have failed validation with a 400 is accepted instead.

ENDPOINT

POST https://api.speakap.io/html/sanitizer

REQUEST

• URI: /html/sanitizer
• Method: POST
• Content-Type: application/json
• Authentication: OAuth 2.0

Request Body

Example

{
    "input": "<div>Hello <b>world</b></div>"
}

Response

{
    "sanitizedHtml": "<p>Hello <strong>world</strong></p>"
}

Output tags

The result only ever contains these tags, with only these attributes.

Each attribute below is dropped on its own when the schema would reject its value; the element stays:

Text attributes such as data-title, data-description or data-embed-type are kept as given; data-embed-type is free text. Every other attribute — class included — is stripped.

Media blocks

Media always ends up as its own top-level <figure> with a data-rel that names its kind:

A <figure> always holds exactly one media element. Everything else in it is moved out:

• Several images or videos become one figure each, in order.
• Paragraphs, headings and loose text follow the figure(s) as <p>/block content; a block left empty once its media is taken out is dropped.
• The first caption goes to the image figure it belongs to (the one before it, otherwise the next one); captions of other kinds, and any extra caption, become a <p> after the figure.
• A figure without any media is unwrapped: its caption or text becomes a <p>, an empty one disappears.
• A <video> without its own src takes the first <source>'s; <source> children and controls are dropped.
• A link around media (<a href><img></a>) is dropped; the media keeps its own block.
• An <a> inside a figure becomes a file/embed block only when the figure is data-rel="file"/"embed" or the anchor is data-rel="attachment", and it wraps no media; its text is kept as plain text. Any other link in a figure is ordinary paragraph text.

Coercion rules

Three rules cover the general case:

1. An unsupported block tag at the top level is replaced by <p>, keeping its content — <div>, <section>, <blockquote>, <pre>.
2. A block tag nested inside a text block becomes an inline <span> — like <p> inside an <li>, as Google Docs produces.
3. Anything else unsupported is reduced to its text, wrapped in a <p> when it would otherwise sit loose at the top level.

Specific behaviours worth knowing:

Void tags come back XML-self-closed (<br />, <img />) so the output parses as XML.