migma

从终端生成、发送、验证和导出人工智能驱动的电子邮件；使用 Migma CLI 管理联系人、细分、标签、域和 Webhooks。

# Migma

Create and send professional, on-brand emails with AI. Your agent can design emails from a prompt, send them instantly through a managed domain, and manage an entire audience — all from the terminal.

Always pass `--json` for structured output.

## First-time setup

If the user hasn't set up yet, run these steps once:

```bash
# 1. Create an instant sending domain (no DNS needed)
migma domains managed create <companyname> --json
# → Sends from: hello@<companyname>.migma.email

# 2. Set a default project (brand)
migma projects list --json
migma projects use <projectId>
```

## Create an email

When the user asks to create, design, or generate an email:

```bash
migma generate "Welcome email for new subscribers" --wait --json
```

The `--wait` flag blocks until the AI finishes. The JSON response includes `conversationId`, `subject`, and `html`.

To save the HTML locally, add `--save ./email.html`. To include a reference image (screenshot, design mockup), add `--image <url>`.

## Send an email

When the user asks to send an email to someone:

```bash
# Send a generated email directly
migma send --to sarah@example.com --subject "Welcome!" \
  --from-conversation <conversationId> \
  --from hello@company.migma.email --from-name "Company" --json

# Or send from a local HTML file
migma send --to sarah@example.com --subject "Hello" \
  --html ./email.html \
  --from hello@company.migma.email --from-name "Company" --json

# Send to an entire segment or tag
migma send --segment <id> --subject "Big News" --html ./email.html \
  --from hello@company.migma.email --from-name "Company" --json

# Personalize with template variables
migma send --to user@example.com --subject "Hi {{name}}" --html ./email.html \
  --from hello@company.migma.email --from-name "Company" \
  --var name=Sarah --var discount=20 --json
```

`--from-conversation` auto-exports the HTML from a generated email — no separate export step.

## Validate an email

When the user wants to check an email before sending:

```bash
migma validate all --html ./email.html --json
migma validate all --conversation <conversationId> --json
```

Returns an overall score plus individual checks: compatibility (30+ email clients), broken links, spelling/grammar, and deliverability/spam score. Individual checks: `migma validate compatibility`, `links`, `spelling`, `deliverability`.

## Export to platforms

When the user wants to export to an ESP or download a file:

```bash
migma export html <conversationId> --output ./email.html
migma export klaviyo <conversationId> --json
migma export mailchimp <conversationId> --json
migma export hubspot <conversationId> --json
migma export pdf <conversationId> --json
migma export mjml <conversationId> --json
```

## Manage contacts

```bash
migma contacts add --email user@example.com --firstName John --json
migma contacts list --json
migma contacts import ./contacts.csv --json
migma contacts remove <id> --json
```

## Manage tags and segments

```bash
migma tags create --name "VIP" --json
migma tags list --json
migma segments create --name "Active Users" --description "..." --json
migma segments list --json
```

## Import a brand

When the user wants to set up a new brand from their website:

```bash
migma projects import https://yourbrand.com --wait --json
migma projects use <projectId>
```

This fetches logos, colors, fonts, and brand voice automatically.

## Error handling

On error, `--json` returns:

```json
{"error": {"message": "Not found", "code": "not_found", "statusCode": 404}}
```

---

## 中文说明

# Migma

使用 AI 创建并发送专业、契合品牌调性的电子邮件。你的代理可以根据提示设计邮件，通过受管域名即时发送，并管理整个受众群体 —— 全部在终端中完成。

始终传递 `--json` 以获得结构化输出。

## 首次设置

如果用户尚未完成设置，请运行以下步骤一次：

```bash
# 1. Create an instant sending domain (no DNS needed)
migma domains managed create <companyname> --json
# → Sends from: hello@<companyname>.migma.email

# 2. Set a default project (brand)
migma projects list --json
migma projects use <projectId>
```

## 创建邮件

当用户要求创建、设计或生成邮件时：

```bash
migma generate "Welcome email for new subscribers" --wait --json
```

`--wait` 标志会阻塞直到 AI 完成。JSON 响应包含 `conversationId`、`subject` 和 `html`。

要将 HTML 保存到本地，添加 `--save ./email.html`。要包含一张参考图片（截图、设计稿），添加 `--image <url>`。

## 发送邮件

当用户要求向某人发送邮件时：

```bash
# Send a generated email directly
migma send --to sarah@example.com --subject "Welcome!" \
  --from-conversation <conversationId> \
  --from hello@company.migma.email --from-name "Company" --json

# Or send from a local HTML file
migma send --to sarah@example.com --subject "Hello" \
  --html ./email.html \
  --from hello@company.migma.email --from-name "Company" --json

# Send to an entire segment or tag
migma send --segment <id> --subject "Big News" --html ./email.html \
  --from hello@company.migma.email --from-name "Company" --json

# Personalize with template variables
migma send --to user@example.com --subject "Hi {{name}}" --html ./email.html \
  --from hello@company.migma.email --from-name "Company" \
  --var name=Sarah --var discount=20 --json
```

`--from-conversation` 会自动从生成的邮件中导出 HTML —— 无需单独的导出步骤。

## 校验邮件

当用户想在发送前检查邮件时：

```bash
migma validate all --html ./email.html --json
migma validate all --conversation <conversationId> --json
```

返回一个总体评分以及各项单独检查：兼容性（30+ 个邮件客户端）、失效链接、拼写/语法以及可送达性/垃圾邮件评分。单项检查：`migma validate compatibility`、`links`、`spelling`、`deliverability`。

## 导出到平台

当用户想导出到 ESP 或下载文件时：

```bash
migma export html <conversationId> --output ./email.html
migma export klaviyo <conversationId> --json
migma export mailchimp <conversationId> --json
migma export hubspot <conversationId> --json
migma export pdf <conversationId> --json
migma export mjml <conversationId> --json
```

## 管理联系人

```bash
migma contacts add --email user@example.com --firstName John --json
migma contacts list --json
migma contacts import ./contacts.csv --json
migma contacts remove <id> --json
```

## 管理标签和细分

```bash
migma tags create --name "VIP" --json
migma tags list --json
migma segments create --name "Active Users" --description "..." --json
migma segments list --json
```

## 导入品牌

当用户想从其网站设置一个新品牌时：

```bash
migma projects import https://yourbrand.com --wait --json
migma projects use <projectId>
```

这会自动获取徽标、颜色、字体和品牌语调。

## 错误处理

发生错误时，`--json` 返回：

```json
{"error": {"message": "Not found", "code": "not_found", "statusCode": 404}}
```