Composer plugins
Add buttons and footers to the composer, change drafts, and hook into creating and sending mail.
Composer plugins use two extension points:
- ComponentRegistry puts React components in named slots in the composer.
- ExtensionRegistry.Composer registers a
ComposerExtensionsubclass that hooks into draft creation, send warnings and sending.
The bundled composer-templates, translation, send-later and link-tracking plugins in apps/desktop/plugins/ are working examples.
Package
Set every window type the composer can appear in:
{
"name": "my-composer-plugin",
"version": "0.1.0",
"main": "./lib/main",
"license": "GPL-3.0-only",
"isOptional": true,
"engines": { "airpost": "^1.38.0" },
"windowTypes": { "default": true, "composer": true, "thread-popout": true }
}
// 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);
}
Composer slots
| Role | Where | Used for |
|---|---|---|
Composer:ActionButton | The action bar | Buttons such as Translate, Templates, Send Later |
Composer:Footer | Below the editor | Status messages |
Composer:ActionBarWorkspace | Below the action bar | A wider work area |
Composer:FromFieldComponents | The From row | Account-related controls |
Components in these slots get these props (from src/features/composer/view.tsx):
interface ComposerInjectedProps {
draft: Message; // the current draft
session: DraftEditingSession; // for changing it
headerMessageId: string;
threadId: string;
isValidDraft: () => Promise<boolean>; // the engine's send checks and their dialogs
}
An action bar button
import React from 'react';
import { Actions, Message, DraftEditingSession, localized } from 'mailspring-exports';
import { IconButton } from 'mailspring-component-kit';
export default class MyComposerButton extends React.Component<{
draft: Message;
session: DraftEditingSession;
}> {
static displayName = 'MyComposerButton';
// The draft prop changes on every keystroke.
shouldComponentUpdate(next) {
return next.session !== this.props.session;
}
_onClick = (e: React.MouseEvent) => {
const originRect = (e.currentTarget as HTMLElement).getBoundingClientRect();
Actions.openPopover(<MyPopover session={this.props.session} />, { originRect, direction: 'up' });
};
render() {
if (this.props.draft.plaintext) return <span />;
return (
<IconButton
variant="toolbar"
label={localized('My Plugin')}
iconUrl="airpost-asset://my-composer-plugin/assets/icon@2x.png"
tabIndex={-1}
onClick={this._onClick}
/>
);
}
}
- Set
static displayName; the registry needs it. - Use
tabIndex={-1}so the button doesn’t take focus from the editor. - Open popovers with
direction: 'up', since the action bar is at the bottom of the composer. - Return an empty element in plaintext mode if your plugin only works with HTML.
A footer
export default class MyStatusBar extends React.Component<{ draft: MessageWithEditorState }> {
static displayName = 'MyStatusBar';
static containerStyles = { textAlign: 'center' as const, width: 580, margin: 'auto' };
render() {
const usingTemplate =
this.props.draft.bodyEditorState?.document.getInlinesByType('templatevar').size > 0;
return usingTemplate ? <div>Press tab to move between blanks.</div> : <div />;
}
}
Changing the draft
Use the session prop:
session.changes.add({ body: '<div>New content</div>' });
session.changes.add({ subject: 'New subject' });
session.changes.add({ to: [new Contact({ email: 'a@example.com', name: 'Alice' })] });
session.changes.commit(); // save now instead of after the debounce
changes.add() takes a partial Message. Rapid calls are coalesced into one save. Writing body (HTML) updates the editor’s state, and draft.bodyEditorState holds the editor’s Slate value; prefer session.changes.add({ body }) for changes from code.
Store per-draft plugin state as metadata:
const metadata = draft.metadataForPluginId('my-plugin');
session.changes.addPluginMetadata('my-plugin', { enabled: true });
ComposerExtension
Subclass ComposerExtension (from mailspring-exports) and override the static hooks you need.
prepareNewDraft
Runs once when the app creates a new draft, before it is shown. The engine has already built the draft, added the signature and removed tracking images. Mutating draft directly is fine here. Drafts created by the CLI, airpost-mcp or the web client don’t pass through it.
static prepareNewDraft({ draft }) {
draft.body = draft.body + '<div>-- Sent from My Plugin</div>';
draft.pristine = false; // keep it from being discarded as empty
}
warningsForSending
Return phrases for the confirmation shown before sending, in the form “Send phrase1 and phrase2?”:
static warningsForSending({ draft }) {
return draft.subject ? [] : ['without a subject'];
}
applyTransformsForSending
Changes the body just before it is sent; it must be reversible. It runs when you press Send in the app, and the result goes to the engine, which keeps it through the undo window. Sends started outside the app (the CLI, airpost-mcp, the web client, and scheduled sends the engine runs on its own) don’t run it.
static applyTransformsForSending({ draft, draftBodyRootNode, recipient }) {
if (draft.plaintext || !draft.metadataForPluginId('my-tracking')) return;
const img = document.createElement('img');
img.src = `https://track.example.com/open/${draft.headerMessageId}`;
draftBodyRootNode.appendChild(img);
}
recipient is set when the body is built per recipient.
sendActions
Adds options to the Send button’s menu:
static sendActions() {
return [{
title: 'Send Later',
iconUrl: 'airpost-asset://my-plugin/assets/icon@2x.png',
isEnabled: ({ draft }) => true,
performSendAction: ({ draft }) => { /* queue tasks */ },
}];
}
title also appears in the default send behaviour setting (core.sending.defaultSendType).
Editor plugins
The composer’s rich-text editor is Slate v0. Editor plugins (custom inline nodes such as template variables and emoji, marks, key handling, editor toolbar buttons) implement ComposerEditorPlugin from src/components/composer-editor/types.ts and are registered statically in the plugins array in src/components/composer-editor/conversion.tsx. A third-party plugin can’t add one at runtime, so this is a change to the app itself; see Contributing.
If you do work on one, read docs/desktop/creating-composer-plugins.md in the repository, which covers renderNode and renderMark with targetIsHTML, serialization rules, the next() chain and void nodes.