Polotno
Export & Import

Email Export

Turn a Polotno design page into email HTML that keeps its text live with the @polotno/email-export JavaScript package, in Node.js or the browser

The @polotno/email-export package turns one page of Polotno design JSON into HTML you can send as an email, in Node.js or in the browser. Text stays real, selectable HTML text wherever Gmail, Outlook, Apple Mail and Yahoo can all show it in place. Everything else is drawn by Image Export, the editor's own renderer, into images behind and around that text.

Live text is selectable, searchable and read aloud, scales with the reader's font size and survives blocked images.

Installation

npm install @polotno/email-export

Runtime

It runs in Node.js 22.13 or newer and in the browser. The package ships separate Node and browser builds, and your bundler or runtime picks the right one. To pick one directly, import @polotno/email-export/node or @polotno/email-export/browser.

Basic Usage

import { jsonToEmailHTML } from '@polotno/email-export';

// create your API key here: https://polotno.com/cabinet
const { html, images } = await jsonToEmailHTML(store.toJSON(), {
  key: 'YOUR_API_KEY',
  // Email clients block inline images: each image is hosted.
  uploadImage: async ({ bytes, mimeType, name }) => {
    return await myBucket.put(name, bytes, mimeType); // an absolute https URL
  },
});

The email is 600 px wide, the width email clients are built around. The page scales to it, and its images are drawn at twice that for sharp high-density screens. A part of the page that is one colour is a coloured table cell with no image, so a page of text on one colour needs no uploadImage.

One call exports one page: the page named by pageId, or the first page.

How It Works

  1. Each text element is checked against what Gmail, classic and new Outlook, Apple Mail and Yahoo can all render. Text that passes stays live; text that does not is drawn into the image, and a text-rasterized warning says why.
  2. The page is drawn once, with the live text's glyphs left out.
  3. The page is cut into a grid of table cells so that each live text sits alone in its cell, and the image is cut along the same grid.
  4. Each cell shows its image slice as a background behind the live text it holds. A slice of one colour is the cell's own colour instead, with no image.

Most text stays live, drawn as close to the editor as each client allows. Opacity, translucent colours, colour filters and a blend mode over one colour are mixed into the text's colours. Lists, sub- and superscripts, justified text, tab stops and the text of table cells stay live. A text-approximated warning names each live text that some client shows differently:

ApproximationWhat some client shows
stroke-droppedNo stroke: Gmail and Outlook drop it
shadow-droppedNo shadow: Gmail and Outlook drop it
gradient-solidOne colour of a gradient fill or stroke

Text is drawn into the image instead when it is rotated or curved, blurred, covered by something drawn above it, too wide for its cell in its fallback font, or in a few other cases that the text-rasterized warning names.

Mobile

A page scales to the email's 600 px, and a phone shows it smaller still. For phones, design a second page and pass it as mobilePageId:

await jsonToEmailHTML(json, {
  uploadImage,
  pageId: 'desktop',
  mobilePageId: 'mobile',
});

The email carries both pages. Below 600 px the mobile page shows at 350 px, which fits every phone inside Gmail's margins; above it, the desktop page shows. Classic Outlook, and clients without media queries, show the desktop page. Both pages share their uploads, so a slice they have in common is hosted once.

Fonts

Gmail, Outlook and Yahoo do not load web fonts. Live text names the design font first and a fallback after it; Apple Mail and iOS load the design font. The fallback is Georgia for serif-looking family names, Courier New for monospace ones and Arial otherwise. Each line keeps the editor's line breaks and never re-wraps: a text with a line that would not fit its cell in the fallback font is drawn into the image.

Options

OptionDefaultMeaning
uploadImage({ bytes, mimeType, name, width, height }) => Promise<url>; needed when the page has more than flat colour
keyYour Polotno API key
pageIdfirst pagePage to export
mobilePageIdA page for phones (Mobile)
onWarningconsole.warnCalled for each warning

textOverflow, textSplitAllowed, skipFontError, skipImageError, blockPrivateNetwork, fetchGuard, allowLocalFiles and signal are passed to Image Export, as documented there.

Warnings

A warning has a stable code, a message, and the pageId and, where it has one, the elementId it is about.

CodeMeaning
text-rasterizedA text is drawn into the image. details.reason says why
text-approximatedA live text some client shows differently; details.approximations
font-fallbackA design font shows as its fallback where web fonts do not load
text-tightA line height classic Outlook may clip
text-too-smallUnder 14 px after scaling to the email width
text-low-contrastUnder 3:1 against the cell colour shown while images are blocked
html-over-budgetThe HTML is over 80 000 bytes; Gmail clips a message near 102 KB
style-over-budgetWeb-font CSS over Gmail's 16 KB <style> limit; it is left out

Image Export's own warnings are passed through.

Untrusted Designs on a Server

In Node.js the export downloads the design's images, SVGs and fonts through Image Export. Cloud-metadata addresses are blocked by default. When the design JSON comes from your users, block private addresses too, or replace the check with your own:

await jsonToEmailHTML(json, { uploadImage, blockPrivateNetwork: true });
await jsonToEmailHTML(json, {
  uploadImage,
  fetchGuard: (url) => isAllowed(url),
});

Not Supported

Links on elements (an address or URL written in a text is linked, in the text's colour), text drawn into the image on request, your own fallback fonts, an email width other than 600 px, a title or preheader, stacking one page's elements on phones (design a mobile page instead), several pages in one email, MJML or AMP output, dark-mode overrides and JPEG slices.

Error Handling

Errors are plain Errors with a stable code and details, shared with the other Polotno exporters. Branch on code, then on details.reason, never on the message.

codedetails.reasonWhen
EXPORT_FAILEDinvalid-optionsAn option is out of range, or the page needs uploadImage. details.option names it
EXPORT_FAILEDpage-not-foundNo page has that pageId or mobilePageId
EXPORT_FAILEDupload-faileduploadImage rejected or returned no URL; a rejection's error is the cause

Image Export's errors (DESIGN_INVALID, IMAGE_FAILED, FONT_FAILED) pass through. See Error Handling for the codes every package shares.

On this page