Mailspring Documentation

Technical Documentation: Foundry376/Mailspring

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

💌 Mailspring

Mailspring is a new version of Nylas Mail maintained by one of the original authors. It's faster, leaner, and shipping today! It replaces the JavaScript sync code in Nylas Mail with a new C++ sync engine based on Mailcore2. It uses roughly half the RAM and CPU of Nylas Mail and idles with almost zero "CPU Wakes", which translates to great battery life. It also has an entirely revamped composer and other great new features.

Mailspring's UI is open source (GPLv3) and written in TypeScript with Electron and React - it's built on a plugin architecture and was designed to be easy to extend. Check out CONTRIBUTING.md to get started!

Mailspring's sync engine is spawned by the Electron application and runs locally on your computer. It is open source (GPLv3) and written in C++ and C. For convenience, however, when you set up your development environment, Mailspring uses the latest version of the sync engine we've shipped for your platform so you don't need to pull sources or install its compile-time dependencies.

Features Copy Chapter

Mailspring comes packed with powerful features like Unified Inbox, Snooze, Send
Later, Mail Rules, Templates and more. Mailspring Pro, which you can unlock
with a monthly subscription, adds even more features for people who send a ton
of email: link tracking, read receipts, mailbox analytics, contact and company
profiles. All of these features run in the client - Mailspring does not send
your email credentials to the cloud. For a full list of features, check out
getmailspring.com.

Download Mailspring Copy Chapter

You can download compiled versions of Mailspring for Windows, Mac OS X, and
Linux (deb, rpm and snap) from
https://getmailspring.com/download.

Getting Help Copy Chapter

You can find community-based help and discussion with other Mailspring users on our
Discourse community.

Contributing Copy Chapter

Mailspring is entirely open-source. Pull requests and contributions are
welcome! There are three ways to contribute: building a plugin, building a
theme, and submitting pull requests to the project itself. When you're getting
started, you may want to join our
Discourse so you can ask questions and
learn from other people doing development.

Running Mailspring from Source Copy Section

To install all dependencies and run Mailspring from its source code,
run the following commands from the root directory of the Mailspring repository:

export npm_config_arch=x64 # If you are on an M1 / Apple Silicon Mac
npm install
npm start

You can attach command line parameters by separating them using a double hyphen:

npm start -- --help

Building Mailspring Copy Section

To build Mailspring, you need to run the following command from the root directory
of the Mailspring repository:

npm run-script build

Building A Plugin Copy Section

Plugins lie at the heart of Mailspring and give it its powerful features.
Building your own plugins allows you to integrate the app with other tools,
experiment with new workflows, and more. Follow the Getting Started
guide to write your first plugin in
five minutes.

• To create your own theme, check out the
  Mailspring-Theme-Starter.

• To create your own plugin, check out the
  Mailspring-Plugin-Starter.

A plugin "store" like the Chrome Web Store is coming soon, and will make it
easy for other users to discover plugins you create. (Right now, users need to
"sideload" the plugins into the app by downloading them and copying them into
place.)

You can share and browse Mailspring Plugins, and discuss plugin development
with other developers, on our
Discourse.

Building a Theme Copy Section

The Mailspring user interface is styled using CSS, which means it's easy to
modify and extend. Mailspring comes stock with a few beautiful themes, and
there are many more which have been built by community developers. To start
creating a theme, clone the theme starter!

If you are updating an existing Nylas theme for Mailspring here is a
step by step tutorial.
Notice: as part of the update process you will probably need to import mailspring base variables.

You can share and browse Mailspring Themes, and discuss theme development with other developers, on our Discourse.

Localizing / Translating Copy Section

Mailspring (1.5.0 and above) supports localization. If you're a fluent speaker of
another language, we'd love your help improving translations. Check out the
LOCALIZATION
guide for more information. You can discuss localization and translation with
other developers on our Discourse.

Contributing to Mailspring Core Copy Section

Pull requests are always welcome - check out
CONTRIBUTING
for more information about setting up the development environment, running
tests locally, and submitting pull requests.

Community Plugins (`docs/community-plugins.md`) Copy Section

Community Plugins for Mailspring

This document lists known third-party plugins for Mailspring found on GitHub.

Official Resources Copy Chapter

Functional Plugins Copy Chapter

General Purpose Copy Section

Notifications & System Integration Copy Section

Productivity & Todo Copy Section

Signatures Copy Section

Calendar Integration Copy Section

Encryption / PGP Copy Section

Alternative Backends & Forks Copy Chapter

These projects modify or replace Mailspring's backend services:

Discovering More Plugins Copy Chapter

• GitHub Topic: mailspring-plugin - All plugins tagged with this topic

Creating Your Own Plugin Copy Chapter

To create your own plugin, see:

• Mailspring-Plugin-Starter - Official template
• Creating Composer Plugins - Guide in this repo
• Built-in plugins in app/internal_packages/ for reference (e.g., composer-templates, phishing-detection)

Plugin Installation Copy Section

Plugins should be copied or symlinked to:

• macOS: ~/Library/Application Support/Mailspring/packages/
• Linux: ~/.config/Mailspring/packages/
• Windows: %APPDATA%/Mailspring/packages/

You can find this directory by going to Developer > Show Mailsync Logs in Mailspring.

Community Themes (`docs/community-themes.md`) Copy Section

Community Themes for Mailspring

This document lists known third-party themes for Mailspring found on GitHub.

Official Resources Copy Chapter

Popular Theme Collections Copy Chapter

These themes are part of larger theme ecosystems:

Dark Themes Copy Chapter

Light Themes Copy Chapter

Other Themes Copy Chapter

Discovering More Themes Copy Chapter

• GitHub Topic: mailspring-theme - All themes tagged with this topic
• GitHub Topic: mailspring - General Mailspring-related repos

Creating Your Own Theme Copy Chapter

To create your own theme:

1. Clone the Mailspring-Theme-Starter
2. Edit package.json with your theme's name and description
3. Modify the LESS files in styles/:
   • index.less - Main stylesheet
   • ui-variables.less - UI color variables
   • theme-colors.less - Theme color definitions

Theme Installation Copy Section

Install themes via Edit > Install Theme... (or Mailspring > Install Theme... on macOS) and select the theme folder.

Alternatively, copy or symlink themes to:

• macOS: ~/Library/Application Support/Mailspring/packages/
• Linux: ~/.config/Mailspring/packages/
• Windows: %APPDATA%/Mailspring/packages/

Theme Structure Copy Section

my-theme/
├── package.json          # Metadata (name, description, license)
├── styles/
│   ├── index.less        # Main stylesheet
│   ├── ui-variables.less # UI color variables
│   └── theme-colors.less # Theme color definitions
├── LICENSE.md
└── README.md

The package.json should include:

{
  "name": "my-theme",
  "displayName": "My Theme",
  "theme": "ui",
  "version": "1.0.0",
  "engines": {
    "mailspring": "*"
  }
}

Creating Composer Plugins (`docs/creating-composer-plugins.md`) Copy Section

Creating Composer Plugins

This guide covers how to build plugins that extend the Mailspring composer — the email drafting interface. Composer plugins can add toolbar buttons, modify draft content, inject UI components, extend the Slate rich-text editor, and hook into the send lifecycle.

Table of Contents Copy Chapter

• Architecture Overview
• Plugin File Structure
• Plugin Lifecycle
• Adding UI to the Composer
  • Component Roles
  • Props Available to Injected Components
  • Toolbar Buttons (Composer:ActionButton)
  • Footer Components (Composer:Footer)
• Modifying Draft Content
  • Using the DraftEditingSession
  • Working with Plugin Metadata
• ComposerExtension: Draft Lifecycle Hooks
  • prepareNewDraft
  • warningsForSending
  • applyTransformsForSending
  • sendActions
• Extending the Slate Rich-Text Editor
  • Editor Plugin Architecture
  • The ComposerEditorPlugin Interface
  • Rendering Custom Nodes (Void Inlines)
  • HTML Serialization and Deserialization Rules
  • Handling Keyboard Events
  • Adding Editor Toolbar Buttons
  • Top-Level Components (Floating UI)
  • Marks for Transient State
  • Registering Your Editor Plugin
• Complete Examples
  • Example 1: Simple Composer Action Button (Translation)
  • Example 2: Full Composer Plugin with Editor Extension (Templates)
  • Example 3: Inline Autocomplete with Floating UI (Emoji)
• Key Imports Reference
• Design Patterns and Best Practices

Architecture Overview Copy Chapter

The Mailspring composer is built on several layers:

┌──────────────────────────────────────────────────────────┐
│  Composer:ActionButton   Composer:Footer   ...           │  ← Injected via ComponentRegistry
├──────────────────────────────────────────────────────────┤
│  ComposerView  (app/internal_packages/composer/)         │  ← Renders InjectedComponentSets
├──────────────────────────────────────────────────────────┤
│  ComposerEditor (Slate v0 rich-text editor)              │  ← Slate plugins for editor behavior
├──────────────────────────────────────────────────────────┤
│  DraftEditingSession  /  DraftChangeSet                  │  ← Draft state management
├──────────────────────────────────────────────────────────┤
│  ComposerExtension (ExtensionRegistry.Composer)          │  ← Send lifecycle hooks
└──────────────────────────────────────────────────────────┘

There are three distinct plugin systems at play:

1. ComponentRegistry — Injects React components into named slots (roles) in the composer UI.
2. ExtensionRegistry.Composer — Registers ComposerExtension subclasses that hook into draft creation, validation, and sending.
3. Slate Editor Plugins — Extend the rich-text editor with custom nodes, marks, keyboard handling, toolbar buttons, and floating UI.

Most composer plugins use (1) and (2). Plugins that need to introduce new inline content types in the editor body (like template variables or emoji) also use (3).

Plugin File Structure Copy Chapter

app/internal_packages/my-composer-plugin/
├── package.json
├── lib/
│   ├── main.ts              # activate() / deactivate() lifecycle
│   ├── my-button.tsx         # React component for Composer:ActionButton
│   ├── my-extension.ts       # ComposerExtension subclass (optional)
│   └── my-editor-plugin.tsx  # Slate editor plugin (optional)
├── assets/
│   └── [email protected]
└── styles/
    └── my-plugin.less

package.json Copy Section

{
  "name": "my-composer-plugin",
  "version": "0.1.0",
  "main": "./lib/main",
  "title": "My Plugin",
  "description": "Does something useful in the composer.",
  "icon": "./icon.png",
  "license": "GPL-3.0",
  "private": true,
  "isOptional": true,
  "engines": {
    "mailspring": "*"
  },
  "windowTypes": {
    "default": true,
    "composer": true,
    "thread-popout": true
  }
}

windowTypes controls which Electron windows load the plugin:

• default — Main application window
• composer — Composer popout window
• thread-popout — Thread popout window

Most composer plugins should set all three to true.

Plugin Lifecycle Copy Chapter

Every plugin must export activate() and deactivate() from lib/main.ts:

import { ComponentRegistry, ExtensionRegistry } from 'mailspring-exports';
import MyButton from './my-button';
import MyComposerExtension from './my-extension';

export function activate() {
  ComponentRegistry.register(MyButton, { role: 'Composer:ActionButton' });
  ExtensionRegistry.Composer.register(MyComposerExtension);
}

export function deactivate() {
  ComponentRegistry.unregister(MyButton);
  ExtensionRegistry.Composer.unregister(MyComposerExtension);
}

activate() is called when the plugin is enabled (on startup for built-in plugins). deactivate() is called when disabled. Always unregister everything you registered.

Adding UI to the Composer Copy Chapter

Component Roles Copy Section

The composer renders InjectedComponentSet elements at specific named slots called roles. Your plugin registers React components into these roles via ComponentRegistry.register().

Props Available to Injected Components Copy Section

Components registered with a Composer:* role receive these props automatically:

interface ComposerInjectedProps {
  draft: Message;                    // The current draft object
  session: DraftEditingSession;      // Session for applying changes
  headerMessageId: string;           // Unique ID for this draft
  threadId: string;                  // Thread ID (for replies)
  isValidDraft: () => boolean;       // Validates draft before sending
}

Source: app/internal_packages/composer/lib/composer-view.tsx

Toolbar Buttons (Composer:ActionButton) Copy Section

The most common extension point. Your component renders a button in the composer toolbar.

/* Detailed source-code truncated for AI context efficiency. */

Key conventions:

• Always set static displayName — required by ComponentRegistry.
• Use tabIndex={-1} on buttons to avoid stealing focus from the editor.
• Use shouldComponentUpdate to avoid re-rendering on every keystroke.
• Use Actions.openPopover() for dropdown menus, passing direction: 'up' since the toolbar is at the bottom of the composer.
• Use RetinaImg with ContentIsMask mode for icons that match the theme.

Footer Components (Composer:Footer) Copy Section

Footer components appear below the editor body. Used for status messages.

// lib/my-status-bar.tsx
import React from 'react';
import { Message, MessageWithEditorState } from 'mailspring-exports';

export default class MyStatusBar extends React.Component<{
  draft: MessageWithEditorState;
}> {
  static displayName = 'MyStatusBar';

  static containerStyles = {
    textAlign: 'center' as const,
    width: 580,
    margin: 'auto',
  };

  render() {
    // Conditionally render based on draft state
    if (!this._shouldShow(this.props.draft)) {
      return <div />;
    }
    return (
      <div className="my-status-bar">
        Some informational message for the user.
      </div>
    );
  }
}

The templates plugin uses this to display "Press tab to move between blanks" when a template with variables is active. It reads the Slate editor state via draft.bodyEditorState:

_usingTemplate(draft: MessageWithEditorState) {
  return (
    draft.bodyEditorState &&
    draft.bodyEditorState.document.getInlinesByType('templatevar').size > 0
  );
}

Modifying Draft Content Copy Chapter

Using the DraftEditingSession Copy Section

The session prop provides the primary API for modifying drafts:

// Replace the entire body
session.changes.add({ body: '<div>New content</div>' });

// Change other draft fields
session.changes.add({ subject: 'New Subject' });
session.changes.add({ to: [new Contact({ email: '[email protected]', name: 'Alice' })] });

// Commit changes immediately (otherwise debounced ~10s)
session.changes.commit();

session.changes.add() accepts a partial Message object. Changes are batched and debounced — multiple rapid calls are coalesced into a single database write.

Body synchronization: When you write to body (an HTML string), the system automatically converts it to a Slate Value for the editor via convertFromHTML(). If the editor is mounted, the conversion preserves undo history by using Slate's replaceNodeByKey and insertFragment operations.

Source: app/src/flux/stores/draft-editing-session.ts, app/src/flux/stores/draft-change-set.ts

Working with Plugin Metadata Copy Section

Drafts support arbitrary key-value metadata per plugin, persisted alongside the draft:

// Read metadata
const metadata = draft.metadataForPluginId('my-plugin');

// Write metadata (on the session)
session.changes.addPluginMetadata('my-plugin', {
  enabled: true,
  setting: 'value',
});

This is useful for tracking plugin state (e.g., "link tracking is enabled for this draft").

ComposerExtension: Draft Lifecycle Hooks Copy Chapter

ComposerExtension provides static hooks into the draft lifecycle. Subclass it and register via ExtensionRegistry.Composer.register().

Source: app/src/extensions/composer-extension.ts

prepareNewDraft Copy Section

Called once when a brand-new draft is created, before it's displayed:

import { ComposerExtension, Message } from 'mailspring-exports';

export default class MyExtension extends ComposerExtension {
  static prepareNewDraft({ draft }: { draft: Message }) {
    // Modify the draft directly here - this is one of the few
    // places where direct mutation is safe.
    draft.body = draft.body + '<div>-- Sent from My Plugin</div>';

    // Set pristine = false if your changes make the draft
    // "valuable" (so it won't be auto-discarded)
    draft.pristine = false;
  }
}

warningsForSending Copy Section

Return warning phrases displayed in a confirmation dialog before sending:

static warningsForSending({ draft }: { draft: Message }): string[] {
  const warnings = [];
  if (draft.body.includes('<code class="var">')) {
    warnings.push('with unfilled template variables');
  }
  if (!draft.subject) {
    warnings.push('without a subject');
  }
  return warnings;
  // Displayed as: "Send with unfilled template variables and without a subject?"
}

applyTransformsForSending Copy Section

Transform the draft body just before it's sent. Must be reversible.

static applyTransformsForSending({
  draft,
  draftBodyRootNode,  // HTMLElement - only for HTML messages
  recipient,          // Contact - for per-recipient body variants
}: {
  draft: Message;
  draftBodyRootNode?: HTMLElement;
  recipient?: Contact;
}) {
  if (draft.plaintext) return;
  const metadata = draft.metadataForPluginId('my-tracking');
  if (!metadata) return;

  // Insert a tracking pixel
  const img = document.createElement('img');
  img.src = `https://track.example.com/open/${draft.headerMessageId}`;
  img.className = 'my-tracking-pixel';
  draftBodyRootNode.appendChild(img);
}

sendActions Copy Section

Register custom send actions that appear in the send button dropdown:

static sendActions() {
  return [{
    title: 'Send Later',
    iconUrl: 'mailspring://send-later/assets/[email protected]',
    isAvailableForDraft: ({ draft }) => true,
    performSendAction: ({ draft }) => {
      // Custom send logic
    },
  }];
}

Extending the Slate Rich-Text Editor Copy Chapter

This is the most powerful and complex extension point. The composer uses Slate v0 as its rich-text editor framework. Slate plugins can introduce custom inline node types, marks, keyboard shortcuts, toolbar buttons, and floating UI.

Editor Plugin Architecture Copy Section

The editor loads plugins from app/src/components/composer-editor/conversion.tsx:

export const plugins: ComposerEditorPlugin[] = [
  ...InlineAttachmentPlugins,  // Inline images
  ...UneditablePlugins,        // Quoted text, tables, signatures
  ...BaseMarkPlugins,          // Bold, italic, underline, etc.
  ...TemplatePlugins,          // Template variables
  ...EmojiPlugins,             // Emoji insertion
  ...LinkPlugins,              // Hyperlinks
  ...BaseBlockPlugins,         // Blockquote, code blocks
  ...MarkdownPlugins,          // Markdown shortcuts
];

Order matters: Deserialization rules are applied in this order. More specific rules (template ) must come before generic ones (plain ).

The schema defines which node types are void (non-editable):

export const schema = {
  inlines: {
    templatevar: { isVoid: true },
    emoji:       { isVoid: true },
    image:       { isVoid: true },
    uneditable:  { isVoid: true },
  },
  blocks: {
    uneditable:  { isVoid: true },
  },
};

The ComposerEditorPlugin Interface Copy Section

Source: app/src/components/composer-editor/types.ts

interface ComposerEditorPlugin {
  // --- Rendering ---
  renderNode?: (
    props: { node: Block | Inline; children: any; targetIsHTML: boolean;
             attributes?: any; isSelected?: boolean },
    editor: Editor | null,
    next: () => void
  ) => void | JSX.Element;

  renderMark?: (
    props: RenderMarkProps & { targetIsHTML?: boolean },
    editor?: Editor,
    next?: () => void
  ) => void | string | JSX.Element;

  // --- HTML Serialization ---
  rules?: Rule[];   // { deserialize(el, next), serialize(obj, children) }

  // --- Keyboard Events ---
  onKeyDown?: (event: React.KeyboardEvent, editor: Editor, next: () => void) => void;
  onKeyUp?: (event: React.KeyboardEvent, editor: Editor, next: () => void) => void;
  onChange?(editor: Editor, next: () => void);

  // --- UI Components ---
  toolbarComponents?: React.ComponentType<{
    editor: Editor; value: Value; className: string;
  }>[];
  toolbarSectionClass?: string;
  topLevelComponent?: React.ComponentType<{ editor: Editor; value: Value }>;

  // --- Application Commands ---
  appCommands?: { [command: string]: (event: CustomEvent, editor: Editor) => Editor };
}

Each handler receives a next function. Call next() to pass control to the next plugin in the chain. If your plugin handles the event, return without calling next().

Rendering Custom Nodes (Void Inlines) Copy Section

To display custom inline elements in the editor, define a renderNode function. The targetIsHTML flag lets you render differently for the editor UI vs. the serialized HTML email:

export const MY_TYPE = 'mycustomnode';

function renderNode({ node, attributes, children, isSelected, targetIsHTML }, editor, next) {
  if (node.type !== MY_TYPE) return next();

  const name = node.data.get('name');

  if (targetIsHTML) {
    // This JSX becomes the HTML that's saved and sent
    return <span data-my-type={name}>{name}</span>;
  }

  // This JSX is the interactive UI in the editor
  return (
    <span
      {...attributes}
      data-my-type={name}
      className={`my-node ${isSelected ? 'selected' : ''}`}
      contentEditable={false}
    >
      {name}
    </span>
  );
}

Template variables use this pattern — they render as `` in HTML but as styled, non-editable pill elements in the editor:

// From template-plugins.tsx
return (
  <span
    {...attributes}
    data-tvar={name}
    className={`template-variable ${isSelected && 'selected'}`}
    contentEditable={false}
    title={name}
  >
    {name}
  </span>
);

HTML Serialization and Deserialization Rules Copy Section

Rules define how your custom nodes convert to/from HTML. This is critical because drafts are stored as HTML strings and loaded into the Slate editor on open.

const rules: Rule[] = [
  {
    // HTML Element → Slate Node (when loading a draft)
    deserialize(el: Element, next) {
      // Check if this HTML element is one of ours
      if (el.dataset && el.dataset.myType) {
        return {
          object: 'inline',
          type: MY_TYPE,
          data: { name: el.dataset.myType },
        };
      }
      // Return nothing to let other plugins handle this element
    },

    // Slate Node → HTML (when saving/sending a draft)
    serialize(obj, children) {
      if (obj.object !== 'inline' || obj.type !== MY_TYPE) return;
      // Reuse renderNode with targetIsHTML: true
      return renderNode({ node: obj, children, targetIsHTML: true });
    },
  },
];

The template plugin also supports a legacy format by checking for <code class="var">:

deserialize(el, next) {
  let name = el.dataset && el.dataset.tvar;
  if (el.tagName === 'CODE' && el.classList.contains('var')) {
    name = '';  // legacy format
  }
  if (name !== undefined) {
    return { object: 'inline', type: VARIABLE_TYPE, data: { name } };
  }
}

Handling Keyboard Events Copy Section

onKeyDown and onKeyUp let you intercept keyboard input in the editor.

Template Tab Navigation (from template-plugins.tsx):

/* Detailed source-code truncated for AI context efficiency. */

Adding Editor Toolbar Buttons Copy Section

Editor toolbar buttons appear in the formatting toolbar (bold, italic, etc.) — distinct from Composer:ActionButton which is in the composer action bar.

Use the BuildToggleButton factory for simple toggle buttons:

import { BuildToggleButton } from './toolbar-component-factories';

const plugin: ComposerEditorPlugin = {
  toolbarSectionClass: 'my-section',
  toolbarComponents: [
    BuildToggleButton({
      type: MY_TYPE,
      button: {
        iconClass: 'fa fa-tag',
        isActive: (value: Value) => value.inlines.some(i => i.type === MY_TYPE),
        onToggle: (editor: Editor, active: boolean) => {
          if (active) {
            // Remove: convert inline back to text
            const node = editor.value.inlines.find(i => i.type === MY_TYPE);
            editor.removeNodeByKey(node.key).insertText(node.data.get('name'));
          } else {
            // Insert: create new inline from selection or default text
            const node = Inline.create({
              type: MY_TYPE,
              data: {
                name: editor.value.selection.isCollapsed
                  ? 'default'
                  : editor.value.fragment.text,
              },
            });
            editor.insertInlineAtRange(editor.value.selection, node).moveToEnd();
          }
        },
      },
    }),
  ],
};

For custom toolbar buttons, provide your own component:

const MyToolbarButton = ({ value, editor, className }) => {
  const onClick = () => {
    // Modify the editor
    editor.insertInline({ object: 'inline', type: MY_TYPE, data: { name: 'test' } });
    editor.moveToStartOfNextText().focus();
  };

  return (
    <button className={className} onClick={onClick}>
      <i className="fa fa-star" />
    </button>
  );
};

Source: app/src/components/composer-editor/toolbar-component-factories.tsx

Top-Level Components (Floating UI) Copy Section

topLevelComponent renders a React component that floats above the editor. The emoji plugin uses this for the autocomplete dropdown:

const plugin: ComposerEditorPlugin = {
  topLevelComponent: FloatingPicker,
  // ...
};

function FloatingPicker({ editor, value }: { editor: Editor; value: Value }) {
  if (!value.selection.isFocused) return null;

  // Read state from marks or document
  const myMark = value.activeMarks.find(m => m.type === 'my-typing-mark');
  if (!myMark) return null;

  // Position relative to the editor content area
  const sel = document.getSelection();
  const range = sel.getRangeAt(0);
  const target = range.endContainer.parentElement.closest('[data-my-typing]');
  if (!target) return null;

  const parent = target.closest('.RichEditor-content') as HTMLElement;
  const parentRect = parent.getBoundingClientRect();
  const targetRect = target.getBoundingClientRect();

  return (
    <div
      className="my-floating-picker"
      style={{
        position: 'absolute',
        left: targetRect.left - parentRect.left,
        top: targetRect.top + targetRect.height - parentRect.top,
      }}
    >
      {/* Picker content */}
    </div>
  );
}

Marks for Transient State Copy Section

Slate Marks are decorations on text (like bold or italic). The emoji plugin creatively uses marks to store transient autocomplete state:

// When user types ":", add a mark to track the autocomplete session
editor.addMark({
  type: 'emojitype',
  data: { typed: '', suggestions: [], picked: '' },
});

// As user types more, update the mark data with suggestions
function updateMark(editor, existing, { typed, suggestions, picked }) {
  editor.moveAnchorBackward(typed.length);
  editor.removeMark(existing);
  editor.addMark({
    type: 'emojitype',
    data: { typed, suggestions, picked },
  });
  editor.moveToFocus();
}

// The floating picker reads this mark for its state
const emoji = value.activeMarks.find(i => i.type === 'emojitype');
const suggestions = emoji.data.get('suggestions');
const picked = emoji.data.get('picked');

This pattern keeps all autocomplete state inside the document, making it trivially accessible from both keyboard handlers and the floating UI component.

Auto-Replace Patterns Copy Section

The slate-auto-replace package converts text patterns into custom nodes. The template plugin uses this to convert {{name}} into a template variable inline:

import AutoReplace from 'slate-auto-replace';

AutoReplace({
  trigger: '}',                       // Fires when user types }
  before: /({{)([^}]+)(})/,          // Pattern to match before cursor
  change: (editor: Editor, e, matches) => {
    const name = matches.before[2];   // Extract variable name
    const node = Inline.create({
      type: VARIABLE_TYPE,
      data: { name },
    });
    editor.insertInlineAtRange(editor.value.selection, node).moveToEnd();
  },
})

Registering Your Editor Plugin Copy Section

Editor plugins are loaded statically from app/src/components/composer-editor/conversion.tsx. To add yours, import it and add it to the plugins array:

// In conversion.tsx
import MyPlugins from './my-plugins';

export const plugins: ComposerEditorPlugin[] = [
  ...InlineAttachmentPlugins,
  ...UneditablePlugins,
  ...BaseMarkPlugins,
  ...TemplatePlugins,
  ...EmojiPlugins,
  ...MyPlugins,         // Add your plugin here
  ...LinkPlugins,
  ...BaseBlockPlugins,
  ...MarkdownPlugins,
];

If your plugin introduces a void node type, add it to the schema:

export const schema = {
  inlines: {
    // ...existing types...
    [MY_TYPE]: { isVoid: true },
  },
};

Complete Examples Copy Chapter

Example 1: Simple Composer Action Button (Translation) Copy Section

The translation plugin adds a toolbar button that opens a language picker popover and replaces the draft body with a translated version.

Key files: app/internal_packages/translation/

// main.tsx — Lifecycle
export function activate() {
  ComponentRegistry.register(TranslateComposerButton, {
    role: 'Composer:ActionButton',
  });
}

export function deactivate() {
  ComponentRegistry.unregister(TranslateComposerButton);
}

// composer-button.tsx — The button component
export class TranslateComposerButton extends React.Component<{
  draft: Message;
  session: DraftEditingSession;
}> {
  static displayName = 'TranslateComposerButton';

  _onTranslate = async (langName) => {
    Actions.closePopover();
    const translated = await translateMessageBody(this.props.draft.body, langCode);

    // Update the draft body through the session
    this.props.session.changes.add({ body: translated });
    this.props.session.changes.commit();
  };

  _onClick = () => {
    const buttonRect = (ReactDOM.findDOMNode(this) as HTMLElement).getBoundingClientRect();
    Actions.openPopover(
      <Menu
        items={Object.keys(languages)}
        itemContent={item => item}
        onSelect={this._onTranslate}
      />,
      { originRect: buttonRect, direction: 'up' }
    );
  };

  render() {
    if (this.props.draft.plaintext) return <span />;
    return (
      <button tabIndex={-1} className="btn btn-toolbar" onClick={this._onClick}>
        <RetinaImg url="mailspring://translation/assets/[email protected]"
                   mode={RetinaImg.Mode.ContentIsMask} />
      </button>
    );
  }
}

Pattern: ComponentRegistry action button + session.changes.add({ body }) for content modification. No editor plugin needed.

Example 2: Full Composer Plugin with Editor Extension (Templates) Copy Section

The templates plugin is the most complete example. It uses all three plugin systems:

1. ComponentRegistry — TemplatePicker button (Composer:ActionButton) + TemplateStatusBar (Composer:Footer)
2. ExtensionRegistry.Composer — TemplateComposerExtension warns about empty template areas
3. Slate Editor Plugin — template-plugins.tsx adds the templatevar void inline type

The Slate plugin provides:

• A toolbar toggle button (tag icon) to create/remove template variables
• renderNode to display variables as styled pills
• rules for HTML round-tripping (``)
• onKeyDown for Tab/Shift+Tab navigation between variables
• AutoReplace to convert {{name}} shorthand into variable nodes

Template insertion flow:

1. User clicks template picker button → Actions.insertTemplateId()
2. TemplateStore reads template HTML from disk and splits off the optional subject line, which is stored in a <meta name="subject"> tag at the top of the file (see template-file.ts)
3. Template HTML is inserted via session.changes.add({ body: templateHTML + existingContent, subject }) — the subject is only included when the template has one and the draft is not a reply or forward
4. The body setter converts HTML to Slate value, finding `` elements and creating templatevar inline nodes via the deserialization rules
5. TemplateStatusBar detects the variables and shows the "Press tab" hint

Example 3: Inline Autocomplete with Floating UI (Emoji) Copy Section

The emoji plugin demonstrates the most sophisticated editor extension pattern:

• Void inline node (emoji) for inserted emoji, rendered as platform-specific images
• Mark (emojitype) stores transient autocomplete state in the document
• topLevelComponent (FloatingEmojiPicker) reads the mark state and renders a positioned dropdown
• onKeyDown handles Enter/Space (confirm), Arrow keys (navigate suggestions)
• onKeyUp handles character input, triggers suggestion lookup, updates the mark

This "mark as state store" pattern is powerful for any inline autocomplete feature.

Key Imports Reference Copy Chapter

From `mailspring-exports` Copy Section

import {
  // Registries
  ComponentRegistry,
  ExtensionRegistry,

  // Extensions
  ComposerExtension,

  // Flux
  Actions,
  DraftStore,
  DraftEditingSession,
  FeatureUsageStore,
  PreferencesUIStore,

  // Models
  Message,
  MessageWithEditorState,
  Contact,

  // Utilities
  localized,
  PropTypes,
} from 'mailspring-exports';

From `mailspring-component-kit` Copy Section

import {
  RetinaImg,       // Retina-aware images
  Menu,            // Dropdown menu with search, headers, footers
  InjectedComponentSet,
} from 'mailspring-component-kit';

From Slate (for editor plugins) Copy Section

import { Editor, Value, Inline, Block, Mark, Node } from 'slate';
import AutoReplace from 'slate-auto-replace';
import { ComposerEditorPlugin, Rule } from './types';
import { BuildToggleButton } from './toolbar-component-factories';

Design Patterns and Best Practices Copy Chapter

Void Nodes for Non-Editable Inline Content Copy Section

Template variables, emoji, and inline images are all void inlines — the cursor can move around them but can't edit their contents. Define them in the schema as { isVoid: true } and set contentEditable={false} in the rendered element.

Dual Rendering with targetIsHTML Copy Section

Always handle both rendering contexts in renderNode and renderMark:

• targetIsHTML: true — Generating the HTML string that's saved/sent. Use simple, semantic HTML with data-* attributes so your deserialization rules can reconstruct the node.
• targetIsHTML: false — The interactive editor UI. Use rich React components with click handlers, styling, etc.

next() Chain Copy Section

Every onKeyDown, onKeyUp, renderNode, renderMark, and onChange handler receives a next function. Always call next() if your plugin doesn't handle the event, or other plugins won't run. If you do handle the event (e.g., event.preventDefault() on Tab), return without calling next().

Body vs. bodyEditorState Copy Section

The draft has two representations of its body content:

• draft.body — HTML string (used by session.changes.add(), serialization, and ComposerExtension hooks)
• draft.bodyEditorState — Slate Value object (used by the editor and footer components that inspect editor state)

These are kept in sync via ES6 property descriptors. Writing to one lazily invalidates the other. Prefer using session.changes.add({ body }) for programmatic changes.

shouldComponentUpdate Copy Section

The draft prop changes on every keystroke. Components registered with Composer:ActionButton should implement shouldComponentUpdate to avoid unnecessary re-renders unless they actually depend on draft content.

Popover Direction Copy Section

Since the composer toolbar is at the bottom of the composer, use direction: 'up' when opening popovers from toolbar buttons so the popover opens upward.

Undo Redo Task Pattern (`docs/undo-redo-task-pattern.md`) Copy Section

Undo/Redo Task Pattern in Mailspring

This document explains how to implement undoable tasks in Mailspring following the established patterns.

Overview Copy Chapter

Mailspring uses a task-based architecture where operations are represented as Task objects that get queued and executed by the sync engine. The UndoRedoStore automatically tracks tasks that can be undone and provides undo/redo functionality.

How It Works Copy Chapter

Automatic Registration Copy Section

When tasks are queued via Actions.queueTask() or Actions.queueTasks(), UndoRedoStore._onQueue() registers one undo block for them if every task has canBeUndone set. Undo queues each task's createUndoTasks(), which defaults to [createUndoTask()]; redo queues createIdenticalTask(). Tasks marked engineWritesUndoData are reversed from the version the engine streams back (Pattern 3). Actions.queueUndoOnlyTask() registers a task for undo without sending it to the engine (Undo Send).

Task Requirements Copy Section

For a task to be undoable, it must:

1. Set canBeUndone to true. It is a field on Task, so assign it in the constructor; a subclass getter is a type error (TS2611).
2. Implement createUndoTask() that returns a task to reverse the operation
3. Implement description() for the undo toast message

Patterns Copy Chapter

Pattern 1: Simple State Toggle (ChangeStarredTask) Copy Section

For operations that toggle a boolean state:

export class ChangeStarredTask extends ChangeMailTask {
  starred: boolean;

  // Inherited from ChangeMailTask: canBeUndone defaults to true

  createUndoTask() {
    const task = super.createUndoTask();
    task.starred = !this.starred;  // Simply flip the flag
    return task;
  }
}

Pattern 2: State Snapshot (SyncbackMetadataTask, SyncbackEventTask) Copy Section

For operations where the inverse isn't a simple toggle, snapshot the state on the task. See SyncbackEventTask (app/src/flux/tasks/syncback-event-task.ts):

• forUpdating({ event, undoData, description }) takes undoData, the state from before the edit, and snapshots the state being written as newData.
• The constructor sets this.canBeUndone = !!this.undoData, so a task built without undoData (creation, for example) is not undoable.
• createUndoTask() restores undoData and swaps the two snapshots, so undoing the undo reapplies the edit.
• createIdenticalTask() (redo) rebuilds the event from newData rather than reading this.event, which may have been mutated since the task was queued.
• Both re-send their snapshot through matchEventSequence, measured against the ICS this window last queued for the event. A snapshot carries the SEQUENCE it had when captured, and Google answers 409 to one below the SEQUENCE it holds, so a snapshot cannot be sent verbatim. A tie is accepted, and changed VEVENTs go out at one. Both first run revertAddedOverrides, because Google keeps an override a PUT leaves out: an occurrence overridden since the snapshot goes back as the snapshot's series has it.

SyncbackMetadataTask follows the same shape with undoValue.

Pattern 3: Engine-Written Snapshot (ChangeFolderTask) Copy Section

Sometimes the client cannot know the original state when it queues the task. A folder move
is the canonical case: a message may have copies in several folders, and only the sync
engine knows which copies it moved and from where. The engine writes that snapshot onto the
task's data during its local phase (the same mechanism DestroyDraftTask uses to receive
stubIds), and the task streams back to the client as a Task persist delta.

export class ChangeFolderTask extends ChangeMailTask {
  folder: Folder;
  sourceFolderIds: string[];
  undoPlacements?: SourceFoldersByMessageId;     // written by the engine: where each moved copy came from
  restorePlacements?: SourceFoldersByMessageId;  // read by the engine on the undo task

  engineWritesUndoData = true;                   // tells UndoRedoStore to wait for the engine's version

  createUndoTasks() {
    const task = super.createUndoTask();         // isUndo = true
    task.folder = this._firstRestoreFolder();    // for the description only
    task.sourceFolderIds = [this.folder.id];     // the copies to send back are in the destination
    task.restorePlacements = this.undoPlacements;
    return [task];
  }
}

Three consequences for anyone using this pattern:

1. Set engineWritesUndoData = true on the task class. UndoRedoStore.undo() then resolves
   each such task through TaskQueue.waitForPerformLocal() before building the undo, so it
   runs against the engine-updated version. The wait is bounded (and abandoned early when
   the engine never echoes the task back), so an offline engine degrades to an approximate
   undo rather than none. Tasks without the flag, and tasks registered through
   Actions.queueUndoOnlyTask, are reversed immediately from the client's copy.
2. Implement createUndoTasks() when the approximate undo can need several tasks (one per
   original folder), and return [] when nothing can be reversed; createUndoTask() stays
   for callers that can only queue one.
3. createIdenticalTask() (used for redo) must strip the engine-written field so a re-run
   starts with a clean snapshot.

Implementation Steps Copy Chapter

Step 1: Add Undo Data Attributes Copy Section

Add attributes to store the original state:

static attributes = {
  ...Task.attributes,

  undoData: Attributes.Obj({
    modelKey: 'undoData',
  }),
  taskDescription: Attributes.String({
    modelKey: 'taskDescription',
  }),
};

Step 2: Capture State Before Modification Copy Section

Before modifying the model, capture its current state:

function modifyEvent(event: Event, newData: EventData) {
  // Capture BEFORE modifying
  const undoData = {
    ics: event.ics,
    recurrenceStart: event.recurrenceStart,
    recurrenceEnd: event.recurrenceEnd,
  };

  // Now modify
  event.ics = newData.ics;
  event.recurrenceStart = newData.start;
  event.recurrenceEnd = newData.end;

  // Queue with undo support
  Actions.queueTask(SyncbackEventTask.forUpdating({
    event,
    undoData,
    description: localized('Edit event'),
  }));
}

Step 3: Set canBeUndone and implement createUndoTask Copy Section

constructor(data: AttributeValues<typeof YourTask.attributes> = {}) {
  super(data);
  this.canBeUndone = !!this.undoData;
}

createUndoTask(): YourTask {
  if (!this.undoData) {
    throw new Error('Cannot create undo task without undoData');
  }

  // Create task that restores original state
  // Store current state in the undo task's undoData for redo
}

Anti-Patterns to Avoid Copy Chapter

Don't Forget to Capture State First Copy Section

❌ Wrong: Capturing after modification

event.ics = newIcs;  // Modified first!
const undoData = { ics: event.ics };  // Too late - this is the new state

✅ Correct: Capture before modification

const undoData = { ics: event.ics };  // Capture original
event.ics = newIcs;  // Now modify

Testing Undo Copy Chapter

1. Perform the action
2. Press Cmd/Ctrl+Z to undo
3. Verify the model is restored to original state
4. Press Cmd/Ctrl+Shift+Z to redo
5. Verify the model has the modified state again

Related Files Copy Chapter

• app/src/flux/stores/undo-redo-store.ts - UndoRedoStore implementation
• app/src/flux/tasks/task.ts - Base Task class
• app/src/flux/tasks/change-mail-task.ts - Base class for mail changes
• app/src/flux/tasks/syncback-metadata-task.ts - Example of snapshot pattern
• app/src/flux/tasks/syncback-event-task.ts - Calendar event undo implementation
• app/src/flux/tasks/change-folder-task.ts - Engine-written snapshot (undoPlacements)

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~13819 tokens
• Canonical Reference: https://codewiki.google/github.com/Foundry376/Mailspring