@mailchain/sdk

Embeddable SDK for MailChain automation chains — build and run trigger-based email automation flows (start trigger → wait → send email → activity condition → contact-list actions) inside your own product.

The SDK is split so you take only what you need:

| Entry | What it is | Depends on | | --- | --- | --- | | @mailchain/sdk | Core domain types & entities (chains, graphs, nodes) | — | | @mailchain/sdk/island | Headless runtime + React hooks (data, commands, editor state). No UI. | React | | @mailchain/sdk/react | The editor store (Zustand) shared across the UI | React | | @mailchain/sdk/ui | Carved editor UI — canvas, node cards, forms, primitives | React |

Partner SDK. The SDK talks to a MailChain backend and needs a partner session context token + API access to do anything. It is inert without one.

Install

npm install @mailchain/sdk

Peer dependency: React 18. The /react and /ui entries also use @xyflow/react, lucide-react, zustand and swr — your bundler provides and dedupes a single copy of each (they are declared as regular dependencies).

Quick start — chains list (headless + your own UI)

import {
  createMailchainRuntime,
  MailchainProvider,
  useChainsList,
} from '@mailchain/sdk/island';

const runtime = createMailchainRuntime({
  apiBaseUrl: 'https://your-mailchain-host/api',
  // Mint/refresh the partner context token however your host does.
  getAccessToken: async () => currentContextToken,
  permissions: {
    hasPermission: ({ resource, action }) =>
      resource === 'chains' ? myPermissions[action] : false,
  },
  navigation: { openChain: ({ chainId }) => router.push(`/chains/${chainId}`) },
});

function ChainsPage() {
  return (
    <MailchainProvider runtime={runtime}>
      <MyChainsList />
    </MailchainProvider>
  );
}

function MyChainsList() {
  const chains = useChainsList(); // { status, items, commands: { create, refresh } }
  // render items with your own components…
}

Editor UI

The /ui entry ships the carved chain editor (React Flow canvas, node cards, inspector forms). It is theme-driven: components reference design tokens as CSS variables, so you repaint by overriding those variables — no fork, no hex.

import { MailchainSkinProvider } from '@mailchain/sdk/ui';
import '@mailchain/sdk/ui/canvas-overrides.css';

<MailchainSkinProvider skin={{ '--color-indigo-600': '#4b4afb' /* your brand */ }}>
  {/* editor surface */}
</MailchainSkinProvider>;

Defaults to the canonical MailChain palette (canonSkin); pass a partial skin map to override only what differs.

Styling

The /ui components use utility classes that expand to the token CSS variables. If your app uses Tailwind, generate them by scanning the installed bundle:

/* your tailwind entry */
@source '../node_modules/@mailchain/sdk/dist/**/*.{js,mjs}';

Then define the token values (--color-*, --radius-*, --shadow-*, --font-*) in your @theme. See MailchainSkinProvider for the full token list.

Localization

Editor copy resolves through a translator you provide, so all strings live in your own i18n catalogue:

import { MailchainEditorI18nProvider, defaultEditorT } from '@mailchain/sdk/ui';

<MailchainEditorI18nProvider t={myTranslate /* (key, params) => string */}>
  {/* editor */}
</MailchainEditorI18nProvider>;

Unresolved keys fall back to defaultEditorT (bundled English). Interpolation uses {{var}}; plurals use i18next _one / _other suffixes.

Versioning

Pre-1.0 (0.x): minor versions may include breaking changes. Pin an exact version if you need stability.

License

Apache-2.0 — see the NOTICE file for attribution.