Maily.to Documentation

Maily provides an opinionated set of pre-designed components to ensure email compatibility across platforms and browsers. Supported components include:

• Logo
• Buttons and Variants
• Variables
• Text Formatting
• Image
• Alignment
• Divider
• Spacer
• Footer
• Inline Code
• Link Cards
• Section
• Columns
• Repeat
• Show If Condition

To support image uploads, add the ImageUploadExtension to the extensions array. Provide an onImageUpload callback that accepts the file, uploads it to your server, and returns the resulting URL.

import { ImageUploadExtension } from '@maily-to/core/extensions';

<Editor
  extensions={[
    ImageUploadExtension.configure({
      onImageUpload: async (file) => {
        const url = await uploadImage(file);
        return url;
      },
    }),
  ]}
/>

Install the @maily-to/render package using pnpm.

pnpm add @maily-to/render

Install the core package using pnpm. For TypeScript type support, you should also install @tiptap/core as a development dependency.

pnpm add @maily-to/core

# for types
pnpm add -D @tiptap/core

Install the @maily-to/shared package using pnpm to access shared utilities for Maily.

pnpm add @maily-to/shared

To run a development version of Maily locally, follow these steps:

1. Clone the repository.
2. Navigate to the project directory.
3. Set up your environment variables by copying the example config.
4. Configure Google and Github providers in your Supabase project (refer to Supabase auth documentation).
5. Install dependencies using pnpm.
6. Start the development server.

git clone https://github.com/arikchakma/maily.to
cd maily.to
cp ./apps/web/.env.example ./apps/web/.env
pnpm install
pnpm dev

You can start using the Maily Editor immediately by accessing the online playground. This allows you to create beautiful, pre-designed, mobile-ready emails using pre-built components without local setup.

https://maily.to/playground

Use the extensions prop to add custom functionality. You can use MailyKit.configure for built-in features, VariableExtension.extend to customize variable views, or pass your own custom extensions.

import { MailyKit, VariableExtension, getVariableSuggestions } from '@maily-to/core/extensions';

<Editor
  extensions={[
    MailyKit.configure({
      linkCard: false,
    }),
    VariableExtension.extend({
      addNodeView() {
        return ReactNodeViewRenderer(VariableView, {
          className: 'mly:relative mly:inline-block',
          as: 'div',
        });
      },
    }).configure({
      suggestion: getVariableSuggestions(variableTriggerCharacter),
    }),
  ]}
/>

You can render custom UI for a slash command by providing a render function to the block object. The render function receives the editor instance and should return a React element or null if nothing should be rendered.

<Editor
  blocks={[
    {
      title: 'Custom Blocks',
      commands: [
        {
          title: 'Custom Block',
          searchTerms: ['custom'],
          render: (editor) => {
            return <div>Custom Block</div>;
          },
        },
      ],
    },
  ]}
/>

To use the @maily-to/core Editor, import the component and its required CSS. The Editor component accepts contentJson for initial content and provides onCreate and onUpdate callbacks to manage the editor instance (which is a Tiptap editor instance).

import '@maily-to/core/style.css';

import { useState } from 'react';
import { Editor } from '@maily-to/core';
import type { Editor as TiptapEditor, JSONContent } from '@tiptap/core';

type AppProps = {
  contentJson: JSONContent;
};

function App(props: AppProps) {
  const { contentJson: defaultContentJson } = props;
  const [editor, setEditor] = useState<TiptapEditor>();

  return (
    <Editor
      contentJson={defaultContentJson}
      onCreate={setEditor}
      onUpdate={setEditor}
    />
  );
}