Migma API Quickstart

Authenticate

Create an account at migma.ai, then pick the first path that works:

Hosted MCP

Add https://migma.ai/mcp in your agent client and approve access in the browser.

CLI

Install the CLI and run migma login. A browser window opens; the key is stored for you.

Claim-code or CI

Direct agents that cannot complete an OAuth callback, but can call the API, poll, and securely store a credential, should fetch https://api.migma.ai/auth.md. CI and servers set MIGMA_API_KEY.

Do not send agents to Settings to copy a key. Settings keys are for CI and server automation only.

Import Your Brand

Before generating emails, you need to import your brand information:

Node.js SDK

import Migma from 'migma';

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

// importAndWait polls automatically until the brand is ready
const { data, error } = await migma.projects.importAndWait({
  urls: ['https://yourbrand.com']
});

console.log('Project ID:', data.projectId);

cURL

curl -X POST https://api.migma.ai/v1/projects/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://yourbrand.com"],
    "name": "My Brand"
  }'

JavaScript

const response = await fetch('https://api.migma.ai/v1/projects/import', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    urls: ['https://yourbrand.com'],
    name: 'My Brand'
  })
});

const data = await response.json();
console.log('Project ID:', data.data.projectId);

Python

import requests

response = requests.post(
    'https://api.migma.ai/v1/projects/import',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'urls': ['https://yourbrand.com'],
        'name': 'My Brand'
    }
)

data = response.json()
print(f"Project ID: {data['data']['projectId']}")

Brand import is asynchronous. The SDK’s importAndWait handles polling automatically. With raw HTTP, save the projectId and poll the status endpoint or use webhooks.

Generate Your First Email

Once your brand is imported, generate an email:

Node.js SDK

// generateAndWait polls automatically until the email is ready
const { data, error } = await migma.emails.generateAndWait({
  projectId: 'your_project_id',
  prompt: 'Create a welcome email for new subscribers',
  languages: ['en']
});

const firstEmail = data.result.emails[0];
console.log('Email ID:', firstEmail.emailId);
console.log('HTML:', firstEmail.html);
console.log('Screenshot:', firstEmail.screenshotUrl);

cURL

curl -X POST https://api.migma.ai/v1/projects/emails/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "your_project_id",
    "prompt": "Create a welcome email for new subscribers",
    "languages": ["en"]
  }'

JavaScript

const response = await fetch(
  'https://api.migma.ai/v1/projects/emails/generate',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      projectId: projectId,
      prompt: 'Create a welcome email for new subscribers',
      languages: ['en']
    })
  }
);

const data = await response.json();
console.log('Conversation ID:', data.data.conversationId);
console.log('Status:', data.data.status); // 'pending'

Python

response = requests.post(
    'https://api.migma.ai/v1/projects/emails/generate',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'projectId': project_id,
        'prompt': 'Create a welcome email for new subscribers',
        'languages': ['en']
    }
)

data = response.json()
print(f"Conversation ID: {data['data']['conversationId']}")
print(f"Status: {data['data']['status']}")  # 'pending'

Poll for Status

Email generation is asynchronous. Use the SDK’s generateAndWait — it handles polling automatically. Or set up webhooks to get notified when generation completes without polling at all.

Manual polling with the SDK

const { data } = await migma.emails.getGenerationStatus('conversation_id');

if (data.status === 'completed') {
  const firstEmail = data.result.emails[0];
  console.log('Email ID:', firstEmail.emailId);
  console.log('HTML:', firstEmail.html);
}

Get, Edit, and Send the Generated Email

Use emailId from result.emails[] to fetch, prompt-edit, test-send, or send one generated email. This is required for email series because conversationId points at the whole generation.

Node.js SDK

const { data } = await migma.emails.getGenerationStatus(conversationId);

if (data.status === 'completed') {
  const selected = data.result.emails[0];
  const email = await migma.emails.get(selected.emailId);

  console.log('HTML:', email.data.html);
  console.log('Screenshot:', email.data.screenshotUrl);

  await migma.emails.edit(selected.emailId, {
    prompt: 'Make this welcome email shorter and more transactional'
  });

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

cURL

curl https://api.migma.ai/v1/emails/{emailId} \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://api.migma.ai/v1/emails/{emailId}/edit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Make this welcome email shorter and more transactional"}'

curl -X POST https://api.migma.ai/v1/sending \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientType": "email",
    "recipientEmail": "sarah@example.com",
    "from": "hello@yourbrand.migma.email",
    "fromName": "Your Brand",
    "subject": "Welcome",
    "emailId": "EMAIL_ID"
  }'

JavaScript

const response = await fetch(
  `https://api.migma.ai/v1/projects/emails/${conversationId}/status`,
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();

if (data.data.status === 'completed') {
  const selected = data.data.result.emails[0];
  const emailHtml = selected.html;
  const emailId = selected.emailId;

  console.log('Email ID:', emailId);
  console.log('Generated HTML:', emailHtml);
}

Complete Example

Here’s a complete workflow from import to generated HTML:

Node.js SDK

import Migma from 'migma';

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

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

// 2. Generate email (waits for completion automatically)
const email = await migma.emails.generateAndWait({
  projectId: brand.data.projectId,
  prompt: 'Create a welcome email for new subscribers',
  languages: ['en']
});

console.log('Subject:', email.data.result.subject);
const selectedEmail = email.data.result.emails[0];
console.log('Email ID:', selectedEmail.emailId);
console.log('HTML:', selectedEmail.html.substring(0, 200) + '...');

Next steps

Node.js SDK

Full SDK guide with error handling, polling, and all 14 resources

CLI

Generate, send, and validate from your terminal

MCP

Connect Migma to Cursor, Codex, Claude, VS Code, and other AI tools

Skills

Add Migma to AI coding assistants

Set Up Webhooks

Real-time notifications instead of polling

API Reference

Full endpoint documentation

Common Issues

401 Unauthorized

Check that your API key is correct and included in the Authorization header as Bearer YOUR_API_KEY

Import takes too long

Brand imports can take 30-60 seconds. Use webhooks to get notified when complete instead of polling.

Generation fails

Check the error message in the response. Common issues:

Invalid projectId (brand not imported yet)
Prompt is too vague or too long
Rate limit exceeded

HTML looks broken

The generated HTML is optimized for email clients. Run email preflight checks to test compatibility across 30+ clients, or send a test email to yourself first.

Overview

Developer Tools

Guides

API endpoints

Migma API Quickstart

Authenticate

Import Your Brand

Generate Your First Email

Poll for Status

Get, Edit, and Send the Generated Email

Complete Example

Next steps

Node.js SDK

CLI

MCP

Skills

Set Up Webhooks

API Reference

Common Issues

​Authenticate

​Import Your Brand

​Generate Your First Email

​Poll for Status

​Get, Edit, and Send the Generated Email

​Complete Example

​Next steps

Node.js SDK

CLI

MCP

Skills

Set Up Webhooks

API Reference

​Common Issues

Authenticate

Import Your Brand

Generate Your First Email

Poll for Status

Get, Edit, and Send the Generated Email

Complete Example

Next steps

Common Issues