Skip to main content

​
Overview

The OneSignal Drag and Drop Email Builder lets you visually design responsive emails exactly as they appear in recipients’ inboxes — without writing full HTML. You build emails using three core components:
  • Settings – global styles and layout applied across the entire email
  • Rows – horizontal layout containers that control structure and responsiveness
  • Content – individual blocks such as text, images, buttons, and HTML
The sections below cover each component and the recommended order for building an email.
Use the Drag and Drop Email Builder if you want to:
  • Design emails visually without managing full HTML (HTML blocks are available)
  • Reuse rows or templates across campaigns
  • Allow non-technical teammates to safely edit content
If you need full HTML control, custom fonts everywhere, or advanced dark mode logic, use the HTML Editor instead.
Follow this order for the best results and fewer rendering issues:
  1. Configure global styles in Settings
  2. Add layout structure using Rows
  3. Insert Content blocks
  4. Add personalization and links
  5. Add an unsubscribe link (for marketing emails)
  6. Save as a template or send
When finished, your email should:
  • Be no wider than 600px
  • Render cleanly on mobile and desktop
  • Include required compliance links
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.
  • Email wider than 600px — causes horizontal scrolling on mobile and breaks layouts in many clients.
  • Background images in rows — Outlook and several mobile clients do not render them. Use Image blocks instead.
  • 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.

​
Settings

Settings define the foundational layout and styles for your email. These values cascade down to rows and content blocks unless explicitly overridden.
Global settings panel in the Drag and Drop Editor
Design SettingDescription
Content area widthWidth of the email in pixels. Recommended: 600px.
Content area alignmentAlign content left or center.
Background colorColor behind the content area.
Content area background colorColor inside the content area.
Default fontApplied to all text unless overridden. Custom fonts require HTML.
Link colorDefault color for all links.
LanguageSets the HTML lang attribute for accessibility. Defaults to English.
Recommended default: Configure as much styling as possible in Settings to ensure consistency and reduce per-block overrides.

​
Rows

Rows define the horizontal layout of your email. Each row can contain one or more columns, and each column can contain content blocks. Drag and drop rows into the editor to build your structure.
Adding rows to structure an email
Use rows to control layout and spacing. Avoid relying on individual content blocks for major layout decisions.

​
Saved rows

Saved rows let you reuse headers, footers, or repeated sections across emails and templates. Click the save icon on a row to save it.
Saving a row for reuse
Access saved rows from Rows > Saved rows.
Selecting a saved row
Saved row categories:
  • Empty – blank row templates
  • My Saved Rows – rows created by you or your team
  • Sample Rows – OneSignal examples

​
Row properties

Click the outer edge of a row to edit row-level settings.
If you see Content instead of Row when hovering, you’ve selected a content block. Click the outer container edge until the label reads Row.
Row PropertyDescription
BackgroundsColor or image behind the row. Recommended: set background color in Settings for consistency.
BordersBorder color, width, and style.
LayoutShow or hide rows on mobile or desktop.
ColumnsAdd, remove, or resize columns and adjust column padding.
Delete/DuplicateSelect a row and use the delete or duplicate icons to remove or copy it.
Avoid background images in rows. Email client support is inconsistent. If the row contains only an image, use an Image block instead.

​
Content

Content blocks are the elements recipients see — text, images, buttons, dividers, and HTML. Drag a content block into a row column. It automatically adapts to the column width.
Available content blocks
Decision rules for content blocks:
  • Use Text blocks for most copy.
  • Use Image blocks for visuals or custom typography.
  • Use HTML blocks only when you need advanced styling or behavior.

​
Custom fonts

The Drag and Drop Editor supports system fonts by default. To use custom fonts, you must use an HTML block.
HTML block
<!-- Place this into a HTML block at the top of your email -->
<style type="text/css">
  /* Declare Bebas Neue (only loads in clients that support web fonts) */
  @font-face {
    font-family: 'Bebas Neue';
    font-style: normal;
    font-weight: 400;
    src: url('https://fonts.gstatic.com/s/bebasneue/v9/JTUSjIg69CK48gW7PXoo9Wlhzg.ttf') format('truetype');
  }
</style>

<h1 style="font-family:'Bebas Neue', Arial, Helvetica, sans-serif; 
           font-size:36px; line-height:1.2; margin:0; text-transform:uppercase;">
  Welcome!
</h1>
<p style="font-family:Arial, Helvetica, sans-serif; font-size:16px; margin:12px 0 0;">
  Thanks for subscribing.
</p>
Many email clients (including Gmail and Outlook for Windows) do not load web fonts. Use system fonts for body text and reserve custom fonts for headlines only. Always include fallback fonts, or use images for guaranteed typography.

​
Images & video

Upload images directly to the OneSignal dashboard so your team can reuse them. The editor supports cropping, filtering, and other effects. You can also reference externally hosted images and videos by URL — make sure each URL is publicly accessible.
  • 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)
  • Keep individual images under 100–200 KB
  • Total email size (including images) under 1 MB
  • Smaller images mean faster load times and better deliverability
  • 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
  • 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 — Gmail, Outlook, and Apple Mail all render differently
  • Outlook often ignores image dimensions, so set both width and height attributes in HTML
OneSignal enables link tracking by default and supports multi-link tracking.

Links

Configure link tracking, multi-link tracking, and click analytics for email.

Deep linking

Route recipients to specific screens in your app from email links.
All marketing emails must contain an unsubscribe link. Emails without one are more likely to be flagged as spam by inbox providers. When a recipient clicks the default OneSignal unsubscribe link, their email Subscription is automatically set to unsubscribed. Add the [unsubscribe_url] tag to your email using either method:

Unsubscribe links

Compliance requirements and how OneSignal handles unsubscribes.

Custom unsubscribe page

Replace the default unsubscribe flow with your own branded page.

​
HTML blocks

Use HTML blocks when you need control that drag-and-drop content blocks cannot provide:
  • Dark mode overrides — add prefers-color-scheme CSS. See Dark mode styling below.
  • Custom fonts — declare @font-face rules with fallback stacks.
  • Advanced layouts — multi-column grids, conditional content, or Outlook-specific markup.
JavaScript is not supported in email. Use inline CSS — many clients strip <style> tags, classes, and IDs.

​
Personalization

Use Liquid templating to insert subscriber-specific content like names, tags, or fallback values. Example: {{ first_name | default: "there" }}
Using Liquid templating to personalize messages

Message personalization

Available personalization variables and how to use them.

Using Liquid syntax

Conditionals, filters, loops, and advanced Liquid patterns.

​
Dark mode

Most emails render acceptably in dark mode without changes. However, emails with brand colors, logos on white backgrounds, or colored sections often need adjustments.

​
Do I need dark mode styling?

Add dark mode overrides if your email includes any of the following:
  • Brand-colored sections — saturated colors become harsh in dark mode and hurt readability
  • Logos or icons on white/light backgrounds — the background may invert while the image stays light, making it invisible
  • Text on colored backgrounds — inverted backgrounds can clash with non-inverted text colors
  • Call-to-action buttons — button backgrounds may invert to unexpected colors
If your email is mostly text with minimal styling, the default rendering is usually acceptable.

​
Preview dark mode in the editor

Use the Preview Mode button to get a general preview of dark mode rendering. This preview is an approximation — actual rendering varies by inbox provider (see the client behavior table below).
Preview mode in the Drag and Drop Editor
Light and dark mode toggle in the Drag and Drop Editor

​
How email clients handle dark mode

Every email client applies dark mode differently. You cannot control this behavior directly, but you can design emails that render well across all modes.
ClientBehaviorRespects prefers-color-scheme CSS?
Apple Mail (iOS/macOS)Full color inversionYes
Gmail (iOS/Android apps)Partial inversion — changes light backgrounds but not all colorsNo
Gmail (Web)No dark mode renderingN/A
Outlook (Windows)Full inversion using Word rendering engineNo — ignores most CSS overrides
Outlook (Mac/iOS)Partial inversionYes
Yahoo MailPartial inversionNo
Samsung MailFull inversionNo
Common dark mode failures to watch for:
  • Disappearing logos — a dark logo on a transparent PNG becomes invisible on a dark background. Add a white or light outline, or use a version with a built-in light background.
  • Unreadable text — dark text on a light background may stay dark after the background is inverted. Always pair text color overrides with background overrides.
  • Clashing brand colors — saturated brand colors that look great on white become harsh on dark backgrounds. Test desaturated or muted alternatives.
  • Invisible buttons — CTA buttons with dark text on a brand-colored background may lose contrast after partial inversion.
Design tips:
  • Avoid pure white (#FFFFFF) and pure black (#000000). Use off-whites and dark grays to reduce the impact of full-inversion clients.
  • Use transparent PNGs with care. They blend well with any background, but dark logos on transparent backgrounds become invisible in dark mode. Add a light outline or use a version with a built-in background for logos.
  • On images that include text, outline dark text in white to ensure legibility. For white text on a dark background, outline in black.

​
Dark mode styling with drag-and-drop

If only a few elements render poorly in dark mode, you can replace them with HTML blocks and override the styling directly using CSS classes and !important declarations.
1

Add an HTML block to the top of your email

Drag an HTML block into the first row of your email.
Adding an HTML block to the top of your email
2

Add dark mode CSS

Paste the following into the HTML block. The prefers-color-scheme: dark media query applies styles only when the recipient’s email client is in dark mode.
HTML block
<meta name="color-scheme" content="light dark" />
<meta name="supported-color-schemes" content="light dark" />
<style>
  :root {
    color-scheme: light dark;
  }

  @media (prefers-color-scheme: dark) {
    .email-body {
      background-color: #1a1a1a !important;
      color: #f0f0f0 !important;
    }

    .email-header {
      background-color: #2d2d2d !important;
    }

    .email-button {
      background-color: #0a84ff !important;
    }
  }
</style>
3

Replace problem content with HTML blocks

Replace any content blocks that do not render correctly in dark mode with HTML blocks that use the CSS classes defined above.
<div class="email-header" style="background-color: #f5f5f5; padding: 0; text-align: center;">
  <img src="https://dashboard.onesignal.com/assets/email/your-email-strategy-starts-here.jpg" 
       alt="Your email strategy starts here" 
       width="600" 
       style="display: block; width: 100%; max-width: 600px; height: auto;" />
</div>
Return to preview mode to verify the dark mode styles are applied correctly.

​
Save your work

Save your email design as a template for future use.
Save email as a template

​
FAQ

Replace the default [unsubscribe_url] with your own URL. You are responsible for updating the email Subscription status in OneSignal when a recipient unsubscribes. See Create a custom unsubscribe page for setup details.

​
Why does my email look different in Outlook?

Outlook on Windows uses the Microsoft Word rendering engine, which does not support modern CSS. Common issues include ignored max-width, collapsed background images, and missing web fonts. Test in Outlook specifically and use inline CSS with explicit width and height attributes on images.

​
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. Optimize images and remove unused code to stay under this threshold.

​
Can I reuse parts of an email across multiple campaigns?

Yes. Save any row as a Saved Row by clicking the save icon on the row. Saved rows appear under Rows > My Saved Rows and can be dragged into any email. For full email reuse, save the entire design as a template.

​
How do I preview my email before sending?

Use the Preview button in the top toolbar to see how your email renders on desktop and mobile. To send a live test, click Send Test Email and enter a recipient address. Test emails are delivered to the inbox so you can verify rendering, links, and personalization in actual email clients.

​
Do emojis work in emails?

Yes, but they render differently across email clients. Outlook on Windows is the most inconsistent — emojis may appear as black-and-white outlines or boxes. If emojis are part of your subject line or CTA text, test across clients before sending.

​
How do I import an existing HTML email template?

You can bring existing HTML templates into OneSignal three ways:
  1. Forward the email to OneSignal using Email Template forwarding
  2. Use the Create Template API to upload HTML programmatically
  3. Copy-paste your HTML directly into the HTML Editor

Email overview

End-to-end guide to sending email with OneSignal.

Design emails with HTML

Full HTML control, dark mode overrides, and advanced styling.

Email templates

Save and reuse email designs across campaigns.

Unsubscribe links

Add default or custom unsubscribe links for compliance.

Message personalization

Personalize emails with tags, Liquid syntax, and dynamic content.

AB testing

Test subject lines, content, and send times to optimize engagement.