> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with the Migma.ai API in under 5 minutes

## Get Your API Key

First, you'll need to create a Migma.ai account and generate an API key:

<Steps>
  <Step title="Sign Up">
    Create an account at [migma.ai](https://migma.ai)
  </Step>

  <Step title="Navigate to Settings">
    Go to **Settings → Developers → API Keys**
  </Step>

  <Step title="Create API Key">
    Click **Create API Key**, select permissions, and save your key securely
  </Step>
</Steps>

<Warning>
  Store your API key securely! It won't be shown again after creation. Treat it like a password.
</Warning>

<Tip>
  **Prefer the terminal?** Install the [CLI](/cli) with `npm install -g @migma/cli` and run `migma login` to get started — then use commands like `migma generate`, `migma send`, and `migma validate` directly from your shell.
</Tip>

## Import Your Brand

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

```typescript Node.js SDK theme={null}
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);
```

```bash cURL theme={null}
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 JavaScript theme={null}
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 Python theme={null}
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']}")
```

<Info>
  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.
</Info>

## Generate Your First Email

Once your brand is imported, generate an email:

```typescript Node.js SDK theme={null}
// 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);
```

```bash cURL theme={null}
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 JavaScript theme={null}
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 Python theme={null}
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](/webhooks) to get notified when generation completes without polling at all.

<AccordionGroup>
  <Accordion title="Manual polling with the SDK">
    ```typescript theme={null}
    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);
    }
    ```
  </Accordion>
</AccordionGroup>

## 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.

```typescript Node.js SDK theme={null}
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
  });
}
```

```bash cURL theme={null}
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 JavaScript theme={null}
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:

```typescript Node.js SDK theme={null}
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

<CardGroup cols={2}>
  <Card title="Node.js SDK" icon="npm" href="/sdk">
    Full SDK guide with error handling, polling, and all 14 resources
  </Card>

  <Card title="CLI" icon="terminal" href="/cli">
    Generate, send, and validate from your terminal
  </Card>

  <Card title="MCP" icon="server" href="/mcp-server">
    Connect Migma to Cursor, Codex, Claude, VS Code, and other AI tools
  </Card>

  <Card title="Skills" icon="wand-magic-sparkles" href="/skills">
    Add Migma to AI coding assistants
  </Card>

  <Card title="Set Up Webhooks" icon="bolt" href="/webhooks">
    Real-time notifications instead of polling
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Full endpoint documentation
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Check that your API key is correct and included in the `Authorization` header as `Bearer YOUR_API_KEY`
  </Accordion>

  <Accordion title="Import takes too long">
    Brand imports can take 30-60 seconds. Use webhooks to get notified when complete instead of polling.
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="HTML looks broken">
    The generated HTML is optimized for email clients. Run [email preflight checks](/email-editor/email-preflight) to test compatibility across 30+ clients, or send a test email to yourself first.
  </Accordion>
</AccordionGroup>