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

# Design emails with HTML

> Send fully custom branded emails using OneSignal's HTML Editor. Covers supported HTML rules, inline CSS, dark mode, unsubscribe handling, and client limitations.

## Overview

The HTML Editor lets you send fully custom, branded emails using your own HTML.

You should use the HTML Editor when you:

* Need complete control over layout, spacing, and styling
* Already have production-ready HTML email templates
* Are comfortable working within email client limitations

<Info>
  HTML emails are not the same as web pages. Many HTML and CSS features are unsupported or inconsistently rendered across email clients.
</Info>

### Prerequisites

Before using the HTML Editor, make sure you:

* Have experience building responsive HTML emails
* Host all images on publicly accessible URLs (your site, CDN, S3, etc.)

#### Expected outcome

After setup, your email:

* Renders consistently across major clients (Gmail, Outlook, Apple Mail)
* Tracks link clicks correctly
* Includes a working unsubscribe mechanism
* Passes spam and deliverability checks

### Import your own templates

If you already have HTML email templates, you can add them to OneSignal in any of the following ways:

1. Use [Email Template forwarding](./email-template-forwarding)
2. Create templates programmatically using the [Create Template API](/reference/create-template)
3. Copy-paste your HTML into the HTML Editor

<Tip> Start with a proven template rather than writing HTML from scratch. </Tip>

### Design in Figma and export to OneSignal

If your email designs live in Figma, there are two ways to get them into OneSignal as HTML:

* **[Email Love](https://emaillove.com/figma-plugin)**: A Figma plugin that converts your design into production-ready HTML email and uploads it directly to your OneSignal templates. Enter your OneSignal App ID and API key in the plugin's export panel and click upload.
* **[Figma MCP server](https://help.figma.com/hc/en-us/articles/32132100833559-Guide-to-the-Figma-MCP-server)**: Connect Figma to an AI coding tool via the MCP server. Point it at your email design frame and ask it to generate HTML email code, then paste the output into the HTML Editor.

<Warning>
  **Common mistakes that cause rendering or deliverability issues:**

  * **Missing unsubscribe link**: Required for marketing emails. Without one, inbox providers are more likely to flag your email as spam.
  * **Using `<style>` blocks instead of inline CSS**: Most email clients strip `<style>` tags. Always inline your styles.
  * **No fallback fonts**: Custom web fonts only load in a few clients. Always declare system font fallbacks.
  * **Oversized images**: Emails over 1 MB load slowly and may be blocked. Individual images should be under 200 KB.
  * **Unsupported HTML**: JavaScript, `<iframe>`, forms, and embedded media are stripped by email clients.
</Warning>

***

## Use the HTML Editor

When creating an email message, select **HTML Editor** as the editor type.

1. Paste or write your HTML in the editor.
2. Use **Send Test Email** to preview rendering across clients and devices.
3. Fix layout issues before scheduling or sending.

<Frame caption="HTML editor with code input and live preview">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/966f520-html-editor-preheader.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=ceece56a7c1c52b3a51badea42685768" alt="HTML editor with code input and live preview" width="1300" height="1238" data-path="images/docs/966f520-html-editor-preheader.png" />
</Frame>

### Links & tracking

Link tracking is enabled by default for HTML emails. Multi-link tracking is supported, and clicks appear in message reports.

<Columns cols={2}>
  <Card title="Links" icon="link" href="./links#email">
    Configure link tracking, multi-link tracking, and click analytics for email.
  </Card>

  <Card title="Deep linking" icon="arrow-up-right-from-square" href="./deep-linking">
    Route recipients to specific screens in your app from email links.
  </Card>
</Columns>

#### Unsubscribe links

All marketing emails must include an unsubscribe link.

Emails without a valid unsubscribe option are more likely to:

* Be marked as spam
* Hurt sender reputation
* Be blocked by inbox providers

<Tabs>
  <Tab title="OneSignal's default unsubscribe link">
    Include the following placeholder anywhere in your HTML (usually in the footer):

    ```html HTML theme={null}
    <a href="[unsubscribe_url]">Unsubscribe</a>
    ```

    When clicked, this link unsubscribes the recipient's email [Subscription](./subscriptions) in OneSignal.
  </Tab>

  <Tab title="Use a custom unsubscribe page (optional)">
    You can link to your own unsubscribe page, but you must:

    * Capture the unsubscribe action
    * Update the recipient’s email Subscription status

    See [Create a custom unsubscribe page](./create-custom-unsubscribe-page) for more details.

    <Warning> If you use a custom unsubscribe URL and do not update the Subscription, users will continue receiving emails. </Warning>
  </Tab>
</Tabs>

***

## HTML email best practices

### Always use inline CSS

Most email clients strip `<style>` blocks and external stylesheets.

Try this tool: [Responsive Email CSS Inliner](https://htmlemail.io/inline/)

### Dark mode styling

Many email clients apply automatic color inversion when dark mode is enabled. This can cause unpredictable results: buttons may appear with a black background and black text, or logos may disappear. Explicitly define how your email should look in both light and dark modes to prevent these issues.

#### How email clients handle dark mode

| Client                       | Behavior                                                        | Respects `prefers-color-scheme` CSS? |
| ---------------------------- | --------------------------------------------------------------- | ------------------------------------ |
| **Apple Mail** (iOS/macOS)   | Full color inversion                                            | Yes                                  |
| **Gmail** (iOS/Android apps) | Partial inversion; changes light backgrounds but not all colors | No                                   |
| **Gmail** (Web)              | No dark mode rendering                                          | N/A                                  |
| **Outlook** (Windows)        | Full inversion using Word rendering engine                      | No; ignores most CSS overrides       |
| **Outlook** (Mac/iOS)        | Partial inversion                                               | Yes                                  |
| **Yahoo Mail**               | Partial inversion                                               | No                                   |
| **Samsung Mail**             | Full inversion                                                  | No                                   |

#### Best practices

* **Define base styles inline.** Always set background and text colors directly on elements instead of relying on defaults or transparency.
* **Use media queries for dark mode.** Clients that support `@media (prefers-color-scheme: dark)` (Apple Mail, Outlook Mac/iOS) allow you to override styles for dark mode.
* **Apply `!important` sparingly.** Adding `!important` to dark mode overrides helps prevent inboxes from stacking inversion rules on top of your custom styles.
* **Signal theme support.** Include the following meta tags in your HTML `<head>` to reduce auto-inversion:

```html theme={null}
<meta name="color-scheme" content="light dark">
<meta name="supported-color-schemes" content="light dark">
```

* **Avoid pure white and pure black.** Use off-whites and dark grays to reduce the impact of full-inversion clients.
* **Use transparent PNGs with care.** Dark logos on transparent backgrounds become invisible on dark backgrounds. Add a light outline or use a version with a built-in background.

<Note>
  For a step-by-step walkthrough of adding dark mode CSS using the Drag and Drop Editor, see [Dark mode styling with drag-and-drop](./design-emails-with-drag-and-drop#dark-mode-styling-with-drag-and-drop).
</Note>

### Recommended image sizes for email

<AccordionGroup>
  <Accordion title="Aspect ratios">
    * Header/Banner images: `3:1` or `4:1` (e.g., `600×200` or `600×150`)
    * Hero images: `16:9` or `2:1` (e.g., `600×338` or `600×300`)
    * Square images: `1:1` (e.g., `300×300`); good for product grids
    * Thumbnails: `1:1` or `4:3`
    * Max width: `600–700px` is standard (most email clients)
    * Design at `2x` for retina displays (e.g., `1200px` wide, displayed at `600px`)
  </Accordion>

  <Accordion title="File size">
    * Keep individual images under `100–200 KB`
    * Total email size (including images) under `1 MB`
    * Smaller images mean faster load times and better deliverability
  </Accordion>

  <Accordion title="File formats">
    * **JPG**: best for photos
    * **PNG**: best for graphics, logos, and images with transparency
    * **GIF**: for simple animations (keep file size small)
    * **WebP**: not widely supported in email yet; avoid
  </Accordion>

  <Accordion title="General tips">
    * Always include alt text for accessibility and for when images do not load
    * Use inline CSS for styling (many clients strip `<style>` tags)
    * Avoid background images (inconsistent client support)
    * Test across clients, as Gmail, Outlook, and Apple Mail all render differently
    * Outlook often ignores image dimensions, so set both `width` and `height` attributes in HTML
  </Accordion>
</AccordionGroup>

### Add alt text to images

Alt text improves accessibility and ensures information is conveyed even when images are blocked or fail to load. Most major email clients display and style alt text:

| Email Client | Blocks Images? | Shows Alt Text | Styles Alt Text |
| ------------ | -------------- | -------------- | --------------- |
| AOL          | Yes            | Yes            | Yes             |
| Gmail        | Yes            | Yes            | Yes             |
| Yahoo        | Yes            | Yes            | Yes             |
| Outlook      | Sometimes      | Yes            | Yes             |

### Use supported HTML only

Email clients **do not** support:

* JavaScript
* `<iframe>`
* HTML forms
* Embedded audio or video
* CSS positioning or layering tricks

Use links to external pages for interactive or multimedia content.

### Validate before sending

Before sending, check the following:

* All links work (broken links hurt deliverability and can trigger spam filters)
* Unsubscribe link functions correctly
* Test emails render in Gmail, Outlook, and Apple Mail
* Dark mode rendering is acceptable
* HTML uses semantic tags and proper indentation for accessibility and maintainability

<Check> If your email renders correctly in major clients and unsubscribe works, it is ready to send. </Check>

### Personalization

Use Liquid templating to insert subscriber-specific content like names, tags, or fallback values directly in your HTML. Example: `{{ first_name | default: "there" }}`

<Columns cols={2}>
  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Available personalization variables and how to use them.
  </Card>

  <Card title="Using Liquid syntax" icon="code" href="./using-liquid-syntax">
    Conditionals, filters, loops, and advanced Liquid patterns.
  </Card>
</Columns>

***

## FAQ

### Can I reuse my existing email templates?

Yes. Forward them to OneSignal via [Email Template forwarding](./email-template-forwarding), upload them with the [Create Template API](/reference/create-template), or copy-paste the HTML directly into the editor.

### Can I use custom fonts?

Yes, but support varies. Declare custom fonts with `@font-face` and always include system font fallbacks. Outlook on Windows ignores web fonts entirely and falls back to system defaults.

### Why does my email look different in dark mode?

Each email client applies dark mode differently. Some fully invert colors, some partially invert, and Gmail web does not apply dark mode at all. See the [client behavior table](#how-email-clients-handle-dark-mode) above for specifics. Define explicit light and dark mode styles to control rendering.

### What HTML and CSS features are not supported in email?

JavaScript, `<iframe>`, HTML forms, embedded audio/video, and CSS positioning are not supported. Use inline CSS for all styling, as most clients strip `<style>` blocks and external stylesheets.

### Can I add a "view in browser" link to my emails?

OneSignal does not generate a hosted web version of your email. To provide a "view in browser" experience, host the email content on your own website and add a standard HTML link pointing to that hosted page.

### What is the maximum email size?

Keep total email size (HTML + images) under 1 MB. Emails over 102 KB of HTML are clipped by Gmail, which hides content below the fold behind a "View entire message" link.

## Related pages

<Columns cols={3}>
  <Card title="Design emails with drag-and-drop" icon="paintbrush" href="./design-emails-with-drag-and-drop">
    Visual email builder for designing emails without writing full HTML.
  </Card>

  <Card title="Email overview" icon="envelope" href="./email-messaging">
    End-to-end guide to sending email with OneSignal.
  </Card>

  <Card title="Email templates" icon="copy" href="./templates">
    Save and reuse email designs across campaigns.
  </Card>

  <Card title="Unsubscribe links" icon="link-slash" href="./unsubscribe-links-email-subscriptions">
    Add default or custom unsubscribe links for compliance.
  </Card>

  <Card title="Message personalization" icon="user-pen" href="./message-personalization">
    Personalize emails with tags, Liquid syntax, and dynamic content.
  </Card>

  <Card title="Email template forwarding" icon="envelope-open-text" href="./email-template-forwarding">
    Import existing HTML email templates into OneSignal.
  </Card>
</Columns>