# Technical Documentation: Foundry376/Mailspring
> โน๏ธ **Provenance:** Multi-Tier Ingestion ยท [CodeWiki Reference](https://codewiki.google/github.com/Foundry376/Mailspring)
### Overview (README.md)
# ๐ 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](https://github.com/MailCore/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](https://github.com/atom/electron) and [React](https://facebook.github.io/react/) - it's built on a plugin architecture and was designed to be easy to extend. Check out [CONTRIBUTING.md](https://github.com/Foundry376/Mailspring/blob/master/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.](https://github.com/Foundry376/Mailspring-Sync) 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
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](https://getmailspring.com/).
## Download Mailspring
You can download compiled versions of Mailspring for Windows, Mac OS X, and
Linux (deb, rpm and snap) from
[https://getmailspring.com/download](https://getmailspring.com/download).
## Getting Help
You can find community-based help and discussion with other Mailspring users on our
[Discourse community](https://community.getmailspring.com/).
## Contributing
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](https://community.getmailspring.com/) so you can ask questions and
learn from other people doing development.
[](CODE_OF_CONDUCT.md)
### Running Mailspring from Source
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
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
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](https://Foundry376.github.io/Mailspring/) to write your first plugin in
five minutes.
- To create your own theme, check out the
[Mailspring-Theme-Starter](https://github.com/Foundry376/Mailspring-Theme-Starter).
- To create your own plugin, check out the
[Mailspring-Plugin-Starter](https://github.com/Foundry376/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](https://community.getmailspring.com/).
### Building a Theme
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](https://github.com/Foundry376/Mailspring-Theme-Starter)!
If you are updating an existing Nylas theme for Mailspring here is a
[step by step tutorial](https://community.getmailspring.com/t/updating-an-n1-nylas-mail-theme-for-mailspring/195).
Notice: as part of the update process you will probably need to [import mailspring base variables](https://github.com/Foundry376/Mailspring/issues/326#issuecomment-343757775).
You can share and browse Mailspring Themes, and discuss theme development with other developers, on our [Discourse](https://community.getmailspring.com/).
### Localizing / Translating
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](https://github.com/Foundry376/Mailspring/blob/master/LOCALIZATION.md)
guide for more information. You can discuss localization and translation with
other developers on our [Discourse](https://community.getmailspring.com/).
### Contributing to Mailspring Core
Pull requests are always welcome - check out
[CONTRIBUTING](https://github.com/Foundry376/Mailspring/blob/master/CONTRIBUTING.md)
for more information about setting up the development environment, running
tests locally, and submitting pull requests.
---
### Community Plugins (`docs/community-plugins.md`)
# Community Plugins for Mailspring
This document lists known third-party plugins for Mailspring found on GitHub.
## Official Resources
| Repository | Description |
|------------|-------------|
| [Foundry376/Mailspring-Plugin-Starter](https://github.com/Foundry376/Mailspring-Plugin-Starter) | Official plugin template for creating your own plugins |
## Functional Plugins
### General Purpose
| Repository | Description | Stars |
|------------|-------------|-------|
| [Striffly/mailspring-avatars](https://github.com/Striffly/mailspring-avatars) | Adds avatars to contacts in Mailspring | โญ76 |
| [bnesimsysadmin/AI-assistant-mailspring-plugin](https://github.com/bnesimsysadmin/AI-assistant-mailspring-plugin) | AI assistant for composing emails | - |
| [smartium/Mailspring-Plugin](https://github.com/smartium/Mailspring-Plugin) | Community plugin | - |
### Notifications & System Integration
| Repository | Description |
|------------|-------------|
| [ruslansin/launcher-api-support](https://github.com/ruslansin/launcher-api-support) | Adds Unity Launcher API dock notifications |
| [3nws/refresh-on-focus](https://github.com/3nws/refresh-on-focus) | Resync mail on window focus with 5 second cooldown |
### Productivity & Todo
| Repository | Description |
|------------|-------------|
| [jmanuel1/todoer](https://github.com/jmanuel1/todoer) | Automatically add starred emails to local todo.txt |
### Signatures
| Repository | Description |
|------------|-------------|
| [Raymo111/mailspring-plaintext-signatures](https://github.com/Raymo111/mailspring-plaintext-signatures) | Adds plaintext signature support |
### Calendar Integration
| Repository | Description |
|------------|-------------|
| [sham-sheer/edison-mail-calendar](https://github.com/sham-sheer/edison-mail-calendar) | Calendar with Google, Microsoft EWS, and CalDAV integration |
| [AbduT/ETCal-MailSpring](https://github.com/AbduT/ETCal-MailSpring) | Ethiopian Calendar plugin |
### Encryption / PGP
| Repository | Description |
|------------|-------------|
| [NgoHuy/mailspring-keybase](https://github.com/NgoHuy/mailspring-keybase) | Keybase PGP encryption plugin |
| [mirkoschubert/mailspring-pgp](https://github.com/mirkoschubert/mailspring-pgp) | Keybase PGP plugin |
| [dinoboy197/mailspring-openpgp](https://github.com/dinoboy197/mailspring-openpgp) | OpenPGP encryption plugin |
## Alternative Backends & Forks
These projects modify or replace Mailspring's backend services:
| Repository | Description | Stars |
|------------|-------------|-------|
| [1RandomDev/mailspring-api](https://github.com/1RandomDev/mailspring-api) | Self-hosted reimplementation of the Mailspring Sync backend | โญ11 |
| [notpushkin/Mailspring-Libre](https://github.com/notpushkin/Mailspring-Libre) | Libre build with no telemetry (archived) | - |
| [algv/Mailspring-Libre](https://github.com/algv/Mailspring-Libre) | Fork of Mailspring-Libre | - |
| [arthurzenika/Mailspring-Libre](https://github.com/arthurzenika/Mailspring-Libre) | Fork of Mailspring-Libre | - |
| [exprez135/Mailspring-Libre](https://github.com/exprez135/Mailspring-Libre) | Fork of Mailspring-Libre | - |
| [jlgarridol/Mailspring-pro](https://github.com/jlgarridol/Mailspring-pro) | Mailspring-pro variant | - |
## Discovering More Plugins
- [GitHub Topic: mailspring-plugin](https://github.com/topics/mailspring-plugin) - All plugins tagged with this topic
## Creating Your Own Plugin
To create your own plugin, see:
- [Mailspring-Plugin-Starter](https://github.com/Foundry376/Mailspring-Plugin-Starter) - Official template
- [Creating Composer Plugins](./creating-composer-plugins.md) - Guide in this repo
- Built-in plugins in `app/internal_packages/` for reference (e.g., `composer-templates`, `phishing-detection`)
### Plugin Installation
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`)
# Community Themes for Mailspring
This document lists known third-party themes for Mailspring found on GitHub.
## Official Resources
| Repository | Description |
|------------|-------------|
| [Foundry376/Mailspring-Theme-Starter](https://github.com/Foundry376/Mailspring-Theme-Starter) | Official theme template for creating your own themes |
## Popular Theme Collections
These themes are part of larger theme ecosystems:
| Repository | Description | Stars |
|------------|-------------|-------|
| [catppuccin/mailspring](https://github.com/catppuccin/mailspring) | Soothing pastel theme (Catppuccin) | โญ58 |
| [dracula/mailspring](https://github.com/dracula/mailspring) | Official Dracula dark theme | โญ17 |
| [faraadi/mailspring-nord-theme](https://github.com/faraadi/mailspring-nord-theme) | Nordic color scheme | โญ72 |
| [getomni/mailspring](https://github.com/getomni/mailspring) | Omni theme | โญ40 |
| [jakubzet/mailspring-matcha-theme](https://github.com/jakubzet/mailspring-matcha-theme) | Matcha theme | โญ42 |
## Dark Themes
| Repository | Description | Stars |
|------------|-------------|-------|
| [jpminor/mailspring-isaac-dark-theme](https://github.com/jpminor/mailspring-isaac-dark-theme) | Newton-inspired dark theme | โญ23 |
| [asparc/predawn](https://github.com/asparc/predawn) | Predawn (Atom/Sublime Text-inspired) | โญ23 |
| [pierrenel/mailspring-dracula](https://github.com/pierrenel/mailspring-dracula) | Dracula variant | - |
| [GianniLab/Mailspring-Eleven-Dark](https://github.com/GianniLab/Mailspring-Eleven-Dark) | Windows 11-inspired dark | โญ9 |
| [yz2/mailspring-minimal-dark-theme](https://github.com/yz2/mailspring-minimal-dark-theme) | Clean, minimal dark theme | โญ8 |
| [chroxify/Sweet-Mailspring](https://github.com/chroxify/Sweet-Mailspring) | Custom dark theme | โญ8 |
| [ZahidHasan/Dark-Light-Theme-Mailspring](https://github.com/ZahidHasan/Dark-Light-Theme-Mailspring) | Minimalist dark theme | - |
| [mjohnson8165/mailspring-arc-dark](https://github.com/mjohnson8165/mailspring-arc-dark) | Arc Dark theme | - |
| [dennisotugo/Mailspring-Adapta-Theme](https://github.com/dennisotugo/Mailspring-Adapta-Theme) | Adapta Dark theme | โญ15 |
| [opes/mailspring-material](https://github.com/opes/mailspring-material) | Material Theme-inspired | - |
| [joelabair/Mailspring-OnLevel-Theme](https://github.com/joelabair/Mailspring-OnLevel-Theme) | N1 Level Up-inspired | - |
| [joeroe/mailspring-gruvbox-dark](https://github.com/joeroe/mailspring-gruvbox-dark) | Gruvbox color scheme | - |
| [kcaliban/Mailspring-Theme-Gruvbox](https://github.com/kcaliban/Mailspring-Theme-Gruvbox) | Gruvbox theme | - |
| [Infamoustrey/mailspring-theme-dracula](https://github.com/Infamoustrey/mailspring-theme-dracula) | Another Dracula variant | - |
| [luisfpg/Mailspring-Materia-Dark-Theme](https://github.com/luisfpg/Mailspring-Materia-Dark-Theme) | Materia Dark matching | - |
| [runeru/mailspring-runeru-theme](https://github.com/runeru/mailspring-runeru-theme) | GitHub colors-based dark | โญ7 |
| [hakouguelfen/mailspring-theme](https://github.com/hakouguelfen/mailspring-theme) | Doom-One theme | - |
## Light Themes
| Repository | Description | Stars |
|------------|-------------|-------|
| [jpminor/mailspring-isaac-light-theme](https://github.com/jpminor/mailspring-isaac-light-theme) | Newton-inspired light theme | โญ13 |
| [GianniLab/Mailspring-11-light-theme](https://github.com/GianniLab/Mailspring-11-light-theme) | Windows 11-inspired light | โญ7 |
| [dincsi/adwaita-mailspring](https://github.com/dincsi/adwaita-mailspring) | GNOME Adwaita light theme | - |
| [NeoMahler/mailspring-idido](https://github.com/NeoMahler/mailspring-idido) | Polymail-inspired clean theme | โญ10 |
| [danieljimeneznz/mailspring-agapanthus-theme](https://github.com/danieljimeneznz/mailspring-agapanthus-theme) | Inbox/Google Cloud-inspired | - |
## Other Themes
| Repository | Description | Stars |
|------------|-------------|-------|
| [antonioprates/mailspring-matcha-dark-azul](https://github.com/antonioprates/mailspring-matcha-dark-azul) | Manjaro matcha-dark-azul matching | โญ7 |
| [webxperia/mailspring-theme-spark](https://github.com/webxperia/mailspring-theme-spark) | Spark theme | - |
| [m1guelpf/mailspring-theme](https://github.com/m1guelpf/mailspring-theme) | Personalized dark material | - |
| [nukeknurs/Reborn](https://github.com/nukeknurs/Reborn) | "Less is more" minimal theme | - |
| [tynguyen2k1/Mailspring-Nord-Theme](https://github.com/tynguyen2k1/Mailspring-Nord-Theme) | Tokyo Night-style theme | - |
| [Kasjonus/wiertara-theme](https://github.com/Kasjonus/wiertara-theme) | Wiertara theme | - |
| [Morgareth99/Mailspring-Nord](https://github.com/Morgareth99/Mailspring-Nord) | Nord theme variant | - |
| [ralphacpm/Mailspring-Nord-Theme](https://github.com/ralphacpm/Mailspring-Nord-Theme) | Nord theme variant | - |
| [avano/Mailspring-Theme](https://github.com/avano/Mailspring-Theme) | Custom theme | - |
## Discovering More Themes
- [GitHub Topic: mailspring-theme](https://github.com/topics/mailspring-theme) - All themes tagged with this topic
- [GitHub Topic: mailspring](https://github.com/topics/mailspring) - General Mailspring-related repos
## Creating Your Own Theme
To create your own theme:
1. Clone the [Mailspring-Theme-Starter](https://github.com/Foundry376/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
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
```
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:
```json
{
"name": "my-theme",
"displayName": "My Theme",
"theme": "ui",
"version": "1.0.0",
"engines": {
"mailspring": "*"
}
}
```
---
### Creating Composer Plugins (`docs/creating-composer-plugins.md`)
# 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
- [Architecture Overview](#architecture-overview)
- [Plugin File Structure](#plugin-file-structure)
- [Plugin Lifecycle](#plugin-lifecycle)
- [Adding UI to the Composer](#adding-ui-to-the-composer)
- [Component Roles](#component-roles)
- [Props Available to Injected Components](#props-available-to-injected-components)
- [Toolbar Buttons (Composer:ActionButton)](#toolbar-buttons-composeractionbutton)
- [Footer Components (Composer:Footer)](#footer-components-composerfooter)
- [Modifying Draft Content](#modifying-draft-content)
- [Using the DraftEditingSession](#using-the-drafteditigsession)
- [Working with Plugin Metadata](#working-with-plugin-metadata)
- [ComposerExtension: Draft Lifecycle Hooks](#composerextension-draft-lifecycle-hooks)
- [prepareNewDraft](#preparenewdraft)
- [warningsForSending](#warningsforsending)
- [applyTransformsForSending](#applytransformsforsending)
- [sendActions](#sendactions)
- [Extending the Slate Rich-Text Editor](#extending-the-slate-rich-text-editor)
- [Editor Plugin Architecture](#editor-plugin-architecture)
- [The ComposerEditorPlugin Interface](#the-composereditorplugin-interface)
- [Rendering Custom Nodes (Void Inlines)](#rendering-custom-nodes-void-inlines)
- [HTML Serialization and Deserialization Rules](#html-serialization-and-deserialization-rules)
- [Handling Keyboard Events](#handling-keyboard-events)
- [Adding Editor Toolbar Buttons](#adding-editor-toolbar-buttons)
- [Top-Level Components (Floating UI)](#top-level-components-floating-ui)
- [Marks for Transient State](#marks-for-transient-state)
- [Registering Your Editor Plugin](#registering-your-editor-plugin)
- [Complete Examples](#complete-examples)
- [Example 1: Simple Composer Action Button (Translation)](#example-1-simple-composer-action-button-translation)
- [Example 2: Full Composer Plugin with Editor Extension (Templates)](#example-2-full-composer-plugin-with-editor-extension-templates)
- [Example 3: Inline Autocomplete with Floating UI (Emoji)](#example-3-inline-autocomplete-with-floating-ui-emoji)
- [Key Imports Reference](#key-imports-reference)
- [Design Patterns and Best Practices](#design-patterns-and-best-practices)
---
## Architecture Overview
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
```
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/
โ โโโ icon-my-plugin@2x.png
โโโ styles/
โโโ my-plugin.less
```
### package.json
```json
{
"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
Every plugin must export `activate()` and `deactivate()` from `lib/main.ts`:
```typescript
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
### Component Roles
The composer renders `InjectedComponentSet` elements at specific named slots called **roles**. Your plugin registers React components into these roles via `ComponentRegistry.register()`.
| Role | Location | Description |
|------|----------|-------------|
| `Composer:ActionButton` | Toolbar above the editor | Buttons like Translate, Templates, Send Later |
| `Composer:Footer` | Below the editor body | Status bars, informational messages |
| `Composer:ActionBarWorkspace` | Below the action bar | Extended workspace area |
| `Composer:FromFieldComponents` | In the "From" row | Signature picker, account-related UI |
### Props Available to Injected Components
Components registered with a `Composer:*` role receive these props automatically:
```typescript
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)
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)
Footer components appear below the editor body. Used for status messages.
```typescript
// 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 ;
}
return (
Some informational message for the user.
);
}
}
```
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`:
```typescript
_usingTemplate(draft: MessageWithEditorState) {
return (
draft.bodyEditorState &&
draft.bodyEditorState.document.getInlinesByType('templatevar').size > 0
);
}
```
---
## Modifying Draft Content
### Using the DraftEditingSession
The `session` prop provides the primary API for modifying drafts:
```typescript
// Replace the entire body
session.changes.add({ body: '
New content
' });
// Change other draft fields
session.changes.add({ subject: 'New Subject' });
session.changes.add({ to: [new Contact({ email: 'a@b.com', 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
Drafts support arbitrary key-value metadata per plugin, persisted alongside the draft:
```typescript
// 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
`ComposerExtension` provides static hooks into the draft lifecycle. Subclass it and register via `ExtensionRegistry.Composer.register()`.
Source: `app/src/extensions/composer-extension.ts`
### prepareNewDraft
Called once when a brand-new draft is created, before it's displayed:
```typescript
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 + '
-- Sent from My Plugin
';
// Set pristine = false if your changes make the draft
// "valuable" (so it won't be auto-discarded)
draft.pristine = false;
}
}
```
### warningsForSending
Return warning phrases displayed in a confirmation dialog before sending:
```typescript
static warningsForSending({ draft }: { draft: Message }): string[] {
const warnings = [];
if (draft.body.includes('')) {
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
Transform the draft body just before it's sent. Must be reversible.
```typescript
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
Register custom send actions that appear in the send button dropdown:
```typescript
static sendActions() {
return [{
title: 'Send Later',
iconUrl: 'mailspring://send-later/assets/icon-send-later@2x.png',
isAvailableForDraft: ({ draft }) => true,
performSendAction: ({ draft }) => {
// Custom send logic
},
}];
}
```
---
## Extending the Slate Rich-Text Editor
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
The editor loads plugins from `app/src/components/composer-editor/conversion.tsx`:
```typescript
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):
```typescript
export const schema = {
inlines: {
templatevar: { isVoid: true },
emoji: { isVoid: true },
image: { isVoid: true },
uneditable: { isVoid: true },
},
blocks: {
uneditable: { isVoid: true },
},
};
```
### The ComposerEditorPlugin Interface
Source: `app/src/components/composer-editor/types.ts`
```typescript
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)
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:
```typescript
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 {name};
}
// This JSX is the interactive UI in the editor
return (
{name}
);
}
```
Template variables use this pattern โ they render as `` in HTML but as styled, non-editable pill elements in the editor:
```typescript
// From template-plugins.tsx
return (
{name}
);
```
### HTML Serialization and Deserialization Rules
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.
```typescript
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 ``:
```typescript
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
`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
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:
```typescript
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:
```typescript
const MyToolbarButton = ({ value, editor, className }) => {
const onClick = () => {
// Modify the editor
editor.insertInline({ object: 'inline', type: MY_TYPE, data: { name: 'test' } });
editor.moveToStartOfNextText().focus();
};
return (
);
};
```
Source: `app/src/components/composer-editor/toolbar-component-factories.tsx`
### Top-Level Components (Floating UI)
`topLevelComponent` renders a React component that floats above the editor. The emoji plugin uses this for the autocomplete dropdown:
```typescript
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 (
{/* Picker content */}
);
}
```
### Marks for Transient State
Slate **Marks** are decorations on text (like bold or italic). The emoji plugin creatively uses marks to store transient autocomplete state:
```typescript
// 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
The `slate-auto-replace` package converts text patterns into custom nodes. The template plugin uses this to convert `{{name}}` into a template variable inline:
```typescript
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
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:
```typescript
// 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:
```typescript
export const schema = {
inlines: {
// ...existing types...
[MY_TYPE]: { isVoid: true },
},
};
```
---
## Complete Examples
### Example 1: Simple Composer Action Button (Translation)
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/`
```typescript
// main.tsx โ Lifecycle
export function activate() {
ComponentRegistry.register(TranslateComposerButton, {
role: 'Composer:ActionButton',
});
}
export function deactivate() {
ComponentRegistry.unregister(TranslateComposerButton);
}
```
```typescript
// 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(