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-exportRuntime
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
- 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-rasterizedwarning says why. - The page is drawn once, with the live text's glyphs left out.
- 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.
- 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:
| Approximation | What some client shows |
|---|---|
stroke-dropped | No stroke: Gmail and Outlook drop it |
shadow-dropped | No shadow: Gmail and Outlook drop it |
gradient-solid | One 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
| Option | Default | Meaning |
|---|---|---|
uploadImage | ({ bytes, mimeType, name, width, height }) => Promise<url>; needed when the page has more than flat colour | |
key | Your Polotno API key | |
pageId | first page | Page to export |
mobilePageId | A page for phones (Mobile) | |
onWarning | console.warn | Called 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.
| Code | Meaning |
|---|---|
text-rasterized | A text is drawn into the image. details.reason says why |
text-approximated | A live text some client shows differently; details.approximations |
font-fallback | A design font shows as its fallback where web fonts do not load |
text-tight | A line height classic Outlook may clip |
text-too-small | Under 14 px after scaling to the email width |
text-low-contrast | Under 3:1 against the cell colour shown while images are blocked |
html-over-budget | The HTML is over 80 000 bytes; Gmail clips a message near 102 KB |
style-over-budget | Web-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.
code | details.reason | When |
|---|---|---|
EXPORT_FAILED | invalid-options | An option is out of range, or the page needs uploadImage. details.option names it |
EXPORT_FAILED | page-not-found | No page has that pageId or mobilePageId |
EXPORT_FAILED | upload-failed | uploadImage 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.