migma

Migma

Use Migma when the user wants to hand off email marketing to an AI agent: create, update, test, send, or schedule transactional emails and marketing campaigns. Always use --json and treat emailId as the public handle for one generated email.

Use public Migma flow only: emailId plus prompt edits. Migma handles rendering and storage internally; responses return finished HTML, subject, screenshots, and IDs.

If the user wants to install Migma into an existing app, audit current email triggers, or wire product events to Migma sends, use the setup skill instead. This skill is for operating Migma once the workflow is known.

Live presence

Migma shows your activity live in the user's dashboard while you work, so announce yourself before anything else. The CLI and SDK identify you automatically. When calling the REST API directly, send X-Agent-Id: ai:<your-name> (for example ai:claude-code) on every request, and show up before your first work call:

curl -X POST https://api.migma.ai/v1/agent/presence \
  -H "Authorization: Bearer $MIGMA_API_KEY" \
  -H "X-Agent-Id: ai:claude-code" \
  -H "Content-Type: application/json" \
  -d '{"conversationId": "<conversationId>", "status": "connected", "goal": "Recreating the 5 transactional emails this app sends"}'

status accepts connected, disconnected, reading, creating, editing, and sending. Work calls (generate, edit, send) broadcast presence on their own, so this endpoint is for the initial hello, goal updates, and an optional goodbye.

Always include a goal: one sentence, in plain language, stating what you are trying to achieve for the user. The dashboard shows it next to your name. Update it when your mission changes, and announce the outcome when you finish (e.g. {"status": "disconnected", "goal": "Done: 5 transactional emails recreated and wired up"}).

Prompts come from the code, not from Migma

Deciding which emails to create is your job: audit the app you are working in and derive the set from its real product events. Migma designs each email you specify — so every generation prompt must carry your audit evidence: the product event and trigger file, the recipient, the exact variables to include as placeholders, and any existing copy or subject worth preserving.

Create an order confirmation email.
Trigger: successful checkout in orders.service.ts.
Variables: firstName, orderNumber, items, total, deliveryEstimate.
Keep the subject "Your order is confirmed". One CTA to order tracking.

Never send a generic ask like "create the emails this business needs" — it discards everything you learned from the code and Migma will have to guess.

Series

Migma creates related emails as one series in a single request — onboarding sequences, order journeys, win-back flows. Pass count and specify each email in the prompt (numbered, with trigger, variables, and CTA per email, same audit-evidence rule as above). One series request beats separate requests: the emails come out visually consistent, and the user sees one canvas with the whole flow.

The status result returns result.emails[], one entry per email in series order: emailId, slot, subject, preheader, html, screenshotUrl, status, and sendOffsetDays when the series is a timed sequence. Treat each entry as a standalone email from there:

• Store every emailId in your constants — each one sends independently via the sending endpoints, and each maps to its own product event or schedule step.
• For timed sequences, use sendOffsetDays to drive your app's scheduling (day 0, day 2, day 5) — Migma tells you the intended cadence, your app owns the timer.
• Verify and edit per email: each entry has its own html and screenshot to check, and POST /v1/emails/<emailId>/edit fixes one email without touching the rest of the series.

Own the result

You are responsible for the outcome, not just the API calls. After a generation completes, fetch the result (the status endpoint returns html and screenshots), check it against your goal — right emails, correct variables, on-brand, working CTAs — and request edits until it passes. Only report the goal achieved after you verified the output yourself.

Login and setup

migma login
migma whoami --json
migma projects list --json
migma projects use <projectId>
migma domains managed create <companyname> --json

Use a managed domain when the user wants to send without DNS work, for example [email protected].

No API key yet

If MIGMA_API_KEY is not set, register yourself instead of sending the user to dig a key out of settings. Fetch https://api.migma.ai/auth.md and follow it: register your intent with the user's email and your agent name, surface the one-time code and approval link to the user, poll the token endpoint until they approve, then use the returned key as MIGMA_API_KEY. Request only the scopes you need.

Create emails

migma generate "Create a welcome email for new trial users" --wait --json
migma generate "Create a 3-email onboarding series" --count 3 --wait --json

Read conversationId and result.emails[] from the response. Each result.emails[] item has emailId, subject, html, and a screenshot URL when available.

Use references only when the user wants follow-ups, remixes, or similar style:

migma emails list --project <projectId> --limit 5 --json
migma generate "Create a follow-up to the welcome email" --reference <conversationId> --wait --json

Fetch and edit emails

migma emails get <emailId> --output ./email.html --json
migma emails edit <emailId> --prompt "Make this shorter and more transactional" --output ./email.html --json

For a series, pick the exact result.emails[].emailId for the email the user named, edit that one email, then fetch the same emailId if verification is needed.

Test and direct send

migma send-test --email <emailId> --to [email protected] --json

migma send --to [email protected] --subject "Welcome" \
  --email <emailId> \
  --from [email protected] --from-name "Company" --json

migma send --tag <tagId> --subject "Product update" \
  --email <emailId> \
  --from [email protected] --from-name "Company" --json

migma send --segment <segmentId> --subject "Product update" \
  --email <emailId> \
  --from [email protected] --from-name "Company" --json

Use migma send for quick transactional emails, tests, and simple blasts. The CLI chooses the send path from recipient type and Migma settings; do not add unsupported flags.

Marketing campaigns

Use campaigns when the user wants a named marketing send with scheduling, recipient counts, and status tracking.

migma tags list --json
migma segments list --json

migma campaigns create --project <projectId> \
  --name "Monthly Newsletter" \
  --conversation <conversationId> --email <emailId> \
  --from [email protected] --from-name "Company" \
  --recipient-type tag --recipient-id <tagId> --json

migma campaigns send <campaignId> --json
migma campaigns schedule <campaignId> --at "2026-03-15T14:00:00Z" --timezone "America/New_York" --json
migma campaigns get <campaignId> --json

For a series campaign, always pass the selected email's emailId with --email.

Audience

migma contacts add --email [email protected] --first-name Sarah --last-name Chen --json
migma contacts import ./contacts.csv --json
migma contacts list --json

migma tags create --name "VIP" --json
migma tags list --json

migma segments create --name "Active customers" --status subscribed --json
migma segments create --name "VIP customers" --tags <tagId> --json
migma segments list --json

Validate and export

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

migma export html <conversationId> --output ./email.html --json
migma export klaviyo <conversationId> --type html --json
migma export mailchimp <conversationId> --json
migma export hubspot <conversationId> --json

Choose the path

• Create or edit: generate, emails get, emails edit.
• Transactional or one-off send: send-test, then send --email <emailId>.
• Marketing blast without lifecycle tracking: send --tag or send --segment.
• Marketing campaign with schedule/status: campaigns create --email <emailId>, then campaigns send or campaigns schedule.