Migma Node.js SDK

Developer tools — Use the SDK, CLI, OpenClaw, Skills, or MCP to integrate Migma into your workflow

Installation

npm install migma

yarn add migma

pnpm add migma

Requirements: Node.js 18 or later. Authenticate with migma login or MIGMA_API_KEY (CI). Hosted MCP clients should connect https://migma.ai/mcp instead of constructing the SDK by hand.

Quick Start

import Migma from 'migma';

const migma = new Migma(process.env.MIGMA_API_KEY);

// A project holds your brand info (colors, fonts, logos, tone of voice).
// Import one from your website, or use an existing project ID from the dashboard.
const brand = await migma.projects.importAndWait({
  urls: ['https://yourbrand.com']
});

// Generate an email design with AI — returns the finished HTML directly.
const email = await migma.emails.generateAndWait({
  projectId: brand.data.projectId,
  prompt: 'Create a welcome email for new subscribers',
  languages: ['en']
});

if (email.data?.status === 'completed') {
  console.log('Subject:', email.data.result.subject);
  console.log('HTML:', email.data.result.html); // primary email HTML
  console.log('Email ID:', email.data.result.emails[0].emailId);
}

Prefer async? Use migma.emails.generate() to kick off generation without waiting, then set up a webhook to receive an email.generation.completed event when the design is ready — no polling needed.

OpenClaw

Use Migma from WhatsApp, Telegram, and Discord with OpenClaw.

Configuration

const migma = new Migma('your_api_key', {
  baseUrl: 'https://api.migma.ai/v1', // default
  maxRetries: 2,     // retries on 5xx / 429 (default: 2)
  retryDelay: 1000   // delay between retries in ms (default: 1s)
});

Error Handling

Every method returns { data, error } — it never throws:

const { data, error } = await migma.contacts.create({
  email: 'sarah@example.com',
  firstName: 'Sarah',
  status: 'subscribed', // only for contacts with marketing consent
  projectId: 'proj_123'
});

if (error) {
  console.error(error.code);       // e.g. 'validation_error'
  console.error(error.statusCode); // e.g. 400
  console.error(error.message);    // human-readable description
  return;
}

// TypeScript narrows — data is guaranteed non-null here
console.log(data.id);

Error codes: validation_error, not_found, unauthorized, forbidden, rate_limit_exceeded, conflict, timeout, network_error, internal_error, unknown

Async Polling Helpers

Email generation, brand import, and preview creation are asynchronous. The SDK provides *AndWait helpers that poll automatically until the operation completes:

const email = await migma.emails.generateAndWait(
  {
    projectId: 'proj_123',
    prompt: 'Create a product launch email'
  },
  {
    interval: 2000,     // poll every 2s (default)
    maxAttempts: 150,   // give up after 150 polls (default)
    onPoll: (status, attempt) => {
      console.log(`Poll ${attempt}: ${status.status}`);
    }
  }
);

All three polling methods:

Method	Waits for
`migma.emails.generateAndWait()`	Email generation to complete
`migma.projects.importAndWait()`	Brand import to finish
`migma.previews.createAndWait()`	Device preview screenshots

You can cancel any polling operation with an AbortController:

const controller = new AbortController();
setTimeout(() => controller.abort(), 60000); // 60s timeout

const result = await migma.emails.generateAndWait(params, {
  signal: controller.signal
});

Generated emails and series

Generate one email or a full series from the same API. Pass count when you want a specific number of emails; otherwise Migma infers the output from the prompt.

const { data: series } = await migma.emails.generateAndWait({
  projectId: 'proj_123',
  prompt: 'Create a three-email welcome series for new trial users',
  count: 3
});

if (series?.status === 'completed') {
  for (const email of series.result.emails) {
    console.log(email.slot, email.emailId, email.subject);
    console.log(email.html);
    console.log(email.screenshotUrl);
  }
}

result.html and result.subject are always the primary email for backwards compatibility. Use result.emails[] when you need the stable emailId, per-email HTML, screenshots, or series order.

Edit generated emails

Fetch one generated email by ID, or prompt Migma to edit it:

const { data: email } = await migma.emails.get('email_123');
console.log(email.html);
console.log(email.screenshotUrl);

const edited = await migma.emails.edit('email_123', {
  prompt: 'Make this welcome email shorter and more transactional'
});

console.log(edited.data.html);

Email performance

See how a generated email performed across every API send of it, or pull its per-recipient send log:

const { data: metrics } = await migma.emails.metrics('email_123');
console.log(metrics.summary.openRate, metrics.summary.clickRate);

const { data: logs } = await migma.emails.logs('email_123', { limit: 50, status: 'opened' });
console.log(logs.emails);

Numbers arrive asynchronously. Opens are directional — Apple Mail Privacy Protection and bots inflate them — so clicks and delivery are stronger signals.

Resources

SDK resources cover the public v1 surface used by apps and agents (some advanced campaign/preview routes stay HTTP-only).

Resource	Methods	Description
`migma.projects`	`list` `get` `import` `getImportStatus` `retryImport` `importAndWait`	Brand management
`migma.emails`	`list` `generate` `importHtml` `getGenerationStatus` `generateAndWait` `importHtmlAndWait` `get` `edit` `sendTest`	Email generation, HTML import, and prompt editing
`migma.campaigns`	`list` `create` `get` `send` `schedule` `cancel` `archive` `unarchive`	Campaign management
`migma.sending`	`send` `getBatchStatus`	Send emails
`migma.export`	`getFormats` `getStatus` `html` `mjml` `pdf` `klaviyo` `mailchimp` `hubspot`	Export to platforms
`migma.contacts`	`create` `list` `get` `update` `remove` `bulkImport` `getBulkImportStatus` `changeStatus`	Contact management
`migma.tags`	`create` `list` `get` `update` `remove`	Tag management
`migma.segments`	`create` `list` `get` `update` `remove`	Audience segments
`migma.topics`	`create` `list` `get` `update` `remove` `subscribe` `unsubscribe`	Preference topics
`migma.validation`	`all` `compatibility` `links` `spelling` `deliverability`	Email testing
`migma.previews`	`create` `get` `getStatus` `getDevice` `getSupportedDevices` `createAndWait`	Device previews
`migma.domains`	`list` `create` `get` `verify` `update` `remove` `checkAvailability` `listManaged` `createManaged` `removeManaged` `provisionStream` `setup`	Sending domains
`migma.domainPurchases`	`search` `create` `registrations` `listDnsRecords` `addDnsRecord` `removeDnsRecord`	Buy a domain and manage DNS on domains bought in Migma
`migma.billing`	`credits` `upgradeLink`	Plan, remaining credits, Stripe upgrade/portal link (user pays in browser)
`migma.webhooks`	`list` `create` `get` `update` `remove` `test` `getDeliveries` `getEvents` `getStats`	Webhook management
`migma.knowledgeBase`	`list` `add` `update` `remove`	Brand knowledge
`migma.images`	`add` `update` `remove` `updateLogos`	Project images

Complete Example

Here’s a full workflow — import a brand, generate an email, export it, and send:

import Migma from 'migma';

const migma = new Migma(process.env.MIGMA_API_KEY);

// 1. Import your brand
const brand = await migma.projects.importAndWait({
  urls: ['https://yourbrand.com']
});
console.log('Brand imported:', brand.data.projectId);

// 2. Generate an email with AI
const email = await migma.emails.generateAndWait({
  projectId: brand.data.projectId,
  prompt: 'Create a password reset email',
  languages: ['en']
});
console.log('Email ready:', email.data.conversationId);
const selectedEmail = email.data.result.emails[0];
if (!selectedEmail.emailId) throw new Error('No emailId returned');

// 3. Send it
await migma.sending.send({
  recipientType: 'email',
  recipientEmail: 'sarah@example.com',
  from: 'hello@yourbrand.migma.email',
  fromName: 'Your Brand',
  subject: selectedEmail.subject,
  emailId: selectedEmail.emailId,
});

For single-email conversations, conversationId also works. For multi-slot emails and series, send a specific email with emailId:

await migma.sending.send({
  recipientType: 'email',
  recipientEmail: 'sarah@example.com',
  from: 'hello@yourbrand.migma.email',
  fromName: 'Your Brand',
  subject: 'Reset your password',
  emailId: 'email_123'
});

By default, emails send through Migma’s built-in infrastructure. You can also send via Amazon SES, Resend, SendGrid, or Mailgun by connecting your provider and passing providerType in the send call.

Resources

npm

View on npm registry

CLI

Use Migma from the command line

API Reference

Full endpoint documentation

Discord

Get help from the community

Overview

Developer Tools

Guides

API endpoints

Migma Node.js SDK

Installation

Quick Start

OpenClaw

Configuration

Error Handling

Async Polling Helpers

Generated emails and series

Edit generated emails

Email performance

Resources

Complete Example

Resources

npm

CLI

API Reference

Discord

​Installation

​Quick Start

OpenClaw

​Configuration

​Error Handling

​Async Polling Helpers

​Generated emails and series

​Edit generated emails

​Email performance

​Resources

​Complete Example

​Resources

npm

CLI

API Reference

Discord

Installation

Quick Start

Configuration

Error Handling

Async Polling Helpers

Generated emails and series

Edit generated emails

Email performance

Resources

Complete Example

Resources