​
Overview

The HTML Editor in OneSignal allows you to craft highly stylized, branded emails with complete control over layout and design for both desktop and mobile. To make the most of HTML email design, we recommend:
  • Ensure you or a teammate has experience with writing responsive HTML emails that render well across different clients and devices.
  • Host all images in a publicly accessible location, such as your website, AWS, or other reliable hosting platforms.

​
Import your own templates

Already have email templates? You can add them to your OneSignal app with the following options:
  1. Email Template forwarding
  2. Create Template API
  3. Copy-paste your HTML into the HTML Editor

​
Using the HTML editor

Select the HTML Editor option when setting up your message. Enter your HTML code in the left panel. You can use the Send Test Email feature to check how your email renders on mobile and desktop clients.

Image showing HTML editor beside the preview

Link tracking is enabled by default. Multi-link tracking is available. See Links and Deep Linking for more details. All marketing emails should contain an unsubscribe link. Without an unsubscribe link, your emails will have a higher chance of being marked as spam. See Unsubscribe links for more details. OneSignal provides a default unsubscribe link that when used, will unsubscribe the user’s email Subscription. You can also include your own custom unsubscribe URL if desired. Just make sure you correctly manage the email Subscription (details in Create a custom unsubscribe page). Add OneSignal’s default [unsubscribe_url] into your emails via: 
<a href="[unsubscribe_url]">Unsubscribe</a>

​
Best practices

Recommended setup for HTML emails:

​
Use inline CSS

Many email clients strip out embedded or external styles. Always inline your CSS to ensure consistent rendering. Try this tool: Responsive Email CSS Inliner

​
Dark mode styling

Many email clients apply automatic color inversion when a user has dark mode enabled. This behavior can cause unpredictable results, such as buttons appearing with a black background and black text. To ensure consistent rendering, we recommend explicitly defining how your email should look in both light and dark modes. 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 like Apple Mail and Outlook on iOS support @media (prefers-color-scheme: dark) where you can 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:
  <meta name="color-scheme" content="light dark">
  <meta name="supported-color-schemes" content="light dark">
Test across clients. Gmail (iOS, Android, web), Outlook, and Apple Mail all behave differently. Testing helps catch issues early.

​
Add alt tags to images

Alt text improves accessibility and ensures information is conveyed even if images are blocked or fail to load.
Email ClientBlocks Images?Shows Alt TextStyles Alt Text
AOLYesYesYes
GmailYesYesYes
YahooYesYesYes
OutlookSometimesYesYes
Source: Litmus Email Client Support

​
Name and format your HTML

Use semantic HTML and meaningful tag naming for accessibility. This helps screen readers interpret your content more accurately. Also, use standard color formats and proper indentation for maintainability. Broken links reduce deliverability and can flag your emails as spam. Test all links thoroughly before sending.

​
Avoid unsupported HTML

Most email clients do not support the following:
  • JavaScript or Flash
  • Embedded audio or video
  • HTML forms
  • Iframes
  • Text layering
Use hyperlinks to share additional content safely.

​
FAQ

​
How can I use my existing email templates?

See above Import your own templates for details.

​
Can I use custom fonts?

Yes, but keep in mind that not all email clients (such as Outlook) support custom fonts. Unsupported fonts will automatically fall back to default system fonts.