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, run the existing synchronous edit, or start a queued edit:

startEdit and getEditStatus require an SDK build that includes queued email edits. If your installed package does not expose them, use the REST fallback below. Older SDK builds may also retry synchronous edit calls after 5xx or 429; create the client with maxRetries: 0 before making that write, or prefer the idempotent REST async flow.

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

// Existing synchronous edit. The SDK disables automatic retries for this
// unsafe write. After an ambiguous failure, fetch the email before retrying.
const edited = await migma.emails.edit('email_123', {
  prompt: 'Make this welcome email shorter and more transactional'
});

if (edited.error) throw edited.error;
console.log(edited.data.html);

// Queued edit. startEdit creates an idempotency key and reuses it across its
// HTTP retries. Pass an explicit key to reuse it across caller-level retries.
const started = await migma.emails.startEdit(
  'email_123',
  {
    prompt: 'Use a shorter headline',
    label: 'Short headline'
  },
  { idempotencyKey: 'edit-email_123-short-headline' }
);
if (started.error) throw started.error;

const status = await migma.emails.getEditStatus(
  'email_123',
  started.data.editId
);
if (status.error) throw status.error;

if (status.data.status === 'completed' && status.data.result) {
  console.log(status.data.result.html);
}

if (status.data.status === 'failed') {
  console.error(status.data.error, status.data.changesMayHaveBeenSaved);
  // Fetch and inspect the stored email before starting another edit.
}

startEdit(emailId, { prompt, label? }, options?: CallOptions) returns MigmaResult<EmailEditOperation> after the job is durably queued. It requires email:write and email:read; credits are checked when the worker starts, with no AI work on the request path. The initial result can have a terminal status on an idempotent replay, but it never includes result, so read it with getEditStatus(emailId, editId). Poll according to pollAfterMs until the exact edit status is completed or failed. Do not use conversation generation status, because a previous turn may already be completed. There is no editAndWait helper, and failed or stalled rewrites are not automatically retried. Edit time varies with section and image complexity, provider behavior, and retries; no fixed maximum latency is established.

REST fallback

curl -X POST "https://api.migma.ai/v1/emails/EMAIL_ID/edit" \
  -H "Authorization: Bearer $MIGMA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: edit-email_123-short-headline" \
  -d '{"prompt":"Use a shorter headline","label":"Short headline","async":true}'

curl "https://api.migma.ai/v1/emails/EMAIL_ID/edits/EDIT_ID" \
  -H "Authorization: Bearer $MIGMA_API_KEY"

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` `startEdit`* `getEditStatus`* `sendTest`	Email generation, HTML import, and prompt editing. *Queued-edit methods require a build containing them.
`migma.campaigns`	`list` `create` `get` `send` `schedule` `cancel` `archive` `unarchive`	Campaign management
`migma.sending`	`send` `getBatchStatus`	Send emails
`migma.export`	`getFormats` `getStatus` `html` `png` `pdf` `klaviyo` `mailchimp` `hubspot`	Export to platforms
`migma.contacts`	`create` `list` `get` `update` `remove` `bulkImport` `getBulkImportStatus` `createImport` `getImport` `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