@mailmodo/cli

Email lifecycle automation for the AI-native builder generation.

@mailmodo/cli is a command-line tool that analyzes your product, generates a full onboarding and lifecycle email sequence using AI, and deploys it — all from your terminal. It manages everything from domain setup and HTML template generation to live deployment, performance monitoring, and contact management.

Table of Contents

• Installation
• Quick Start
• Commands Reference
  • login
  • logout
  • init
  • emails
  • edit
  • preview
  • deploy
  • deployments
  • sdk
  • domain
  • settings
  • status
  • logs
  • contacts
  • billing
  • report
• SDK / App Integration
• Configuration
• AI Agent Support

Installation

npm install -g @mailmodo/cli

Requires Node.js >= 18.

Verify the installation:

mailmodo --version
mailmodo --help

Quick Start

The primary workflow from zero to deployed email sequence:

1. Authenticate

mailmodo login

You will be prompted to enter your Mailmodo API key. Get one at app.mailmodo.dev.

2. Analyze your product and generate emails

mailmodo init --url https://yourapp.com

The CLI scrapes your product URL, detects your business model, and generates a full email sequence with HTML templates. A mailmodo.yaml config file and a mailmodo/ directory of HTML templates are created in your current working directory.

3. Preview an email

mailmodo preview welcome

Opens a local preview server in your browser. Use --send me@example.com to send yourself a test.

4. Set up your sending domain

mailmodo domain

Follow the prompts to register your domain and sender details. The CLI displays the DNS records you need to add. Verify once propagated:

mailmodo domain --verify

5. Deploy

mailmodo deploy

Validates your configuration, deploys all email sequences, and prints the track() and identify() SDK snippets to wire into your app.

6. Monitor

mailmodo status      # quota usage and per-email metrics
mailmodo logs        # delivery event log

Commands Reference

All commands support two universal flags:

login

Authenticate with Mailmodo using your API key.

mailmodo login

Validates your API key against the Mailmodo API, saves credentials to ~/.mailmodo/config, and performs a silent cloud backup of any existing mailmodo.yaml. If credentials are already saved, displays current account status.

Environment variable shortcut (for CI/CD):

# Linux / macOS
MAILMODO_API_KEY=your_key mailmodo login

# Windows PowerShell
$env:MAILMODO_API_KEY="your_key"; mailmodo login

# Windows CMD
set MAILMODO_API_KEY=your_key && mailmodo login

JSON output shape:

{
  "status": "logged_in",
  "email": "you@example.com",
  "plan": "free",
  "totalFreeRemaining": 500,
  "paidEmailsRemaining": 0,
  "yamlRestored": false
}

logout

Remove saved credentials from this machine.

mailmodo logout

Deletes ~/.mailmodo/config. Does not affect the server-side account.

JSON output shape:

{ "status": "logged_out" }

init

Analyze your product and generate a full email sequence.

mailmodo init
mailmodo init --url https://yourapp.com
mailmodo init --url https://yourapp.com --yes

What init does:

1. Calls the Mailmodo AI to analyze your product URL and detect business model, target user, SaaS model, and brand details.
2. Generates email copy and HTML templates for a complete lifecycle sequence (welcome, onboarding, trial expiry, etc.).
3. Writes mailmodo.yaml to the current directory.
4. Creates a mailmodo/ directory containing one .html file per email.
5. Silently backs up the config and templates to the cloud.

JSON output shape:

{
  "brand": { "name": "...", "color": "...", "url": "..." },
  "emailConfigs": [...],
  "emailStyle": "branded",
  "monthlyCap": 5
}

emails

List and inspect your configured email sequences.

mailmodo emails
mailmodo emails --json

Reads mailmodo.yaml locally and displays a table of all configured emails: ID, trigger event, delay, and subject. In interactive mode, you can select any email to view its full details or open the template in your editor.

JSON output shape:

{
  "emails": [
    {
      "id": "welcome",
      "trigger": "user.signup",
      "delay": 0,
      "subject": "Welcome to MyApp"
    }
  ],
  "total": 4
}

edit

Edit an email using AI-assisted natural language changes.

mailmodo edit <id>
mailmodo edit welcome
mailmodo edit welcome --change "make the subject more urgent"
mailmodo edit welcome --change "rewrite the body focusing on onboarding" --yes

The CLI sends the current template and your change description to the Mailmodo AI, previews the diff (changed vs. unchanged fields), and lets you accept, retry, or skip.

JSON output shape:

Returns the updated email object with a diff property showing which fields changed and which were preserved.

preview

Preview an email in the browser, as plain text, or send a test.

mailmodo preview
mailmodo preview <id>
mailmodo preview welcome --text
mailmodo preview welcome --send me@example.com

In browser mode (default), a local server starts at http://localhost:3421 and opens your browser.

deploy

Deploy, pause, or resume an email sequence.

# Deploy all configured sequences
mailmodo deploy
mailmodo deploy --yes

# Pause a live sequence
mailmodo deploy --pause <sequenceId>

# Resume a paused sequence
mailmodo deploy --resume <sequenceId>
mailmodo deploy --resume <sequenceId> --json

--pause and --resume are mutually exclusive.

Deploy flow:

1. Checks domain verification status; runs domain setup if needed.
2. Validates your email sequence configuration.
3. Shows a pre-deploy summary: domain, sender, email count, and a diff of changes since the last deploy.
4. Prompts for confirmation (skipped with --yes).
5. Deploys and prints the @mailmodo/sdk code snippets to add to your app.

Deploy JSON output shape:

{
  "deployed": true,
  "emailsLive": 4,
  "sequenceId": "seq_abc123",
  "diff": { "added": [], "changed": [], "removed": [] },
  "sdkSnippet": "..."
}

Pause/Resume JSON output shape:

{
  "sequenceId": "seq_abc123",
  "status": "paused",
  "alreadyInStatus": false
}

deployments

List every deployed sequence on this account.

mailmodo deployments
mailmodo deployments --json

Displays a table with product name, status (active / paused), email count, sequence ID, and last-updated date. The sequence IDs shown here are the values to pass to deploy --pause and deploy --resume.

JSON output shape:

{
  "sequences": [
    {
      "sequenceId": "seq_abc123",
      "product": "MyApp",
      "status": "active",
      "emailCount": 4,
      "updatedAt": "2025-06-01T10:00:00Z"
    }
  ],
  "total": 1
}

sdk

Show SDK track() and identify() reference for your deployed sequences.

mailmodo sdk
mailmodo sdk --sequence-id seq_abc123
mailmodo sdk --json

Displays the install command, import line, and copy-ready track() / identify() function calls for each active sequence. See SDK / App Integration for details on using these in your app.

domain

Set up and verify your sending domain.

# Interactive setup (register domain and get DNS records)
mailmodo domain

# Verify DNS records after adding them
mailmodo domain --verify

# Show domain health metrics
mailmodo domain --status

During setup, you are prompted for: domain, sender email (must be @<domain>), from name, reply-to address, and physical business address (required by CAN-SPAM). The CLI outputs the exact DNS records to add to your registrar.

Note: DNS changes take 5–30 minutes to propagate before verification will pass.

settings

View and update project settings.

mailmodo settings
mailmodo settings --set brand_color=#0F3460
mailmodo settings --json

In interactive mode (no flags), displays all settings grouped by category and prompts to edit each one. With --set, updates the specified key directly without prompting.

Settable keys:

status

View email performance metrics and quota usage.

mailmodo status
mailmodo status --json

Displays per-email metrics (sent, open rate, click rate, conversion rate), total monthly sends, and current quota status (free emails remaining or paid blocks consumed).

JSON output shape:

{
  "emails": [
    {
      "id": "welcome",
      "sent": 120,
      "openRate": 0.42,
      "clickRate": 0.15,
      "conversionRate": 0.08
    }
  ],
  "monthlySent": 480,
  "quota": { "free": 20, "paidBlocksUsed": 0 }
}

logs

View email send logs and delivery events.

mailmodo logs
mailmodo logs --email sarah@example.com
mailmodo logs --failed
mailmodo logs --limit 100 --page 2
mailmodo logs --json

JSON output shape:

{
  "entries": [
    {
      "timestamp": "2025-06-01T10:00:00Z",
      "emailId": "welcome",
      "status": "delivered",
      "contact": "sarah@example.com",
      "reason": null
    }
  ],
  "total": 480,
  "page": 1,
  "limit": 50
}

contacts

Manage contacts — search, export, or delete.

# Show summary counts
mailmodo contacts

# Search for a specific contact
mailmodo contacts --search sarah@example.com

# Export all contacts as GDPR-compliant CSV
mailmodo contacts --export

# Hard-delete a contact (GDPR right to erasure)
mailmodo contacts --delete sarah@example.com

Without any flags, displays total, active, unsubscribed, and bounced contact counts.

billing

View billing status, purchase email blocks, set a monthly cap, or add a payment method.

# View current billing status
mailmodo billing
mailmodo billing --status

# Open Stripe checkout to add or update a payment method
mailmodo billing --checkout

# Purchase email blocks immediately
mailmodo billing --purchase 3

# Set a monthly sending cap (paid tier)
mailmodo billing --cap 5

# Set cap with auto-refill when quota runs low
mailmodo billing --cap 5 --auto-charge-block-count 2

Each block = 1,000 emails. --monthly-cap and --auto-charge-block-count require a saved payment method.

report

Fetch a detailed analytics report with flexible filtering and grouping.

# Quick report for the last 7 days
mailmodo report --preset last7d

# Group by email template
mailmodo report --preset last30d --group-by emailId

# Custom date range, raw event entries
mailmodo report --from 2025-05-01 --to 2025-06-01 --output entries

# Filter to a specific sequence and event type
mailmodo report --preset last30d --sequence seq_abc123 --event opened

# Paginate through entries
mailmodo report --preset last7d --output entries --page 2 --limit 100

mailmodo report --preset last7d --json

--preset and --from/--to are mutually exclusive.

SDK / App Integration

After deploying a sequence, the CLI prints the exact code to add to your application. You can always retrieve it with:

npm install @mailmodo/sdk

import { track, identify } from '@mailmodo/sdk';

track(event, properties)

Called when a lifecycle event happens in your app. This triggers the email configured for that event.

// Example: trigger the "welcome" email on sign-up
track('myApp$user.signup', {
  contactEmailId: user.email,
  first_name: user.firstName,
  onboarding_url: `https://app.example.com/onboard/${user.id}`,
});

identify(email, properties)

Updates contact properties used by conditional send logic.

// Example: update onboarding status to conditionally suppress follow-up emails
identify(user.email, {
  onboarding_not_completed: user.onboardingStep < 3,
});

The mailmodo sdk command (or the post-deploy output) shows the exact event names and properties for each sequence in your account.

Configuration

Credentials — ~/.mailmodo/config

Stores your API key and account metadata. Written by mailmodo login, deleted by mailmodo logout. Never commit this file.

{
  "apiKey": "mk_...",
  "email": "you@example.com",
  "totalFreeRemaining": 500
}

Environment variable override: Set MAILMODO_API_KEY to bypass the config file entirely — useful in CI/CD pipelines and Docker containers.

Project Config — mailmodo.yaml

Created by mailmodo init in your current working directory. This is the source of truth for your email sequence. Commit it to version control.

project:
  name: MyApp
  url: https://myapp.com
  description: Project management for remote teams
  type: b2b_saas
  targetUser: engineering managers
  saasModel: subscription
  pricingModel: per_seat

  domain: myapp.com
  fromEmail: hello@myapp.com
  fromName: MyApp
  replyTo: support@myapp.com
  address: 123 Main St, San Francisco, CA 94105, US

  emailStyle: branded # branded | plain
  brandColor: '#1A56DB'
  logoUrl: https://cdn.myapp.com/logo.png

  monthlyCap: 5 # paid tier — blocks per month (1 block = 1,000 emails)
  webhookUrl: https://myapp.com/webhooks/mailmodo

emails:
  - id: welcome
    trigger: user.signup
    delay: 0
    subject: 'Welcome to MyApp, {{first_name}}!'
    template: welcome.html
    style: branded
    previewText: 'Your account is ready.'
    goal: Drive user to complete the first key action
    ctaText: Get Started

  - id: day3-nudge
    trigger: user.signup
    delay: '3d'
    subject: 'Quick tip for getting started'
    template: day3-nudge.html
    condition: 'onboarding_not_completed == true'

HTML Templates — mailmodo/

Each email in mailmodo.yaml maps to an HTML file in the mailmodo/ directory:

mailmodo/
  welcome.html
  day3-nudge.html
  trial-expiry.html

Templates are generated by mailmodo init and editable directly or via mailmodo edit. They are automatically synced to the Mailmodo cloud as a backup on every modifying command and restored automatically if the local file is missing.

AI Agent Support

All commands support two flags designed for headless and automated environments:

API key via environment variable

Set MAILMODO_API_KEY to authenticate without a config file:

MAILMODO_API_KEY=mk_... mailmodo deploy --yes --json

Example: fully non-interactive deploy in CI

MAILMODO_API_KEY=$MAILMODO_API_KEY \
  mailmodo deploy --yes --json | jq '.sequenceId'

Example: AI agent loop

# Generate emails, skip all prompts, get structured output
mailmodo init --url https://yourapp.com --yes --json

# Edit with a specific instruction, no confirmation
mailmodo edit welcome --change "add a P.S. with the link to our docs" --yes --json

# Deploy immediately
mailmodo deploy --yes --json

License

MIT © Mailmodo