@myapihq/cli 1.0.84 → 1.1.0-wip.1

package/dist/commands/email.js

@@ -1,204 +1,586 @@
 import { email as sdkEmail } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, printJson, info } from '../output.js';
-import { sleep } from '../utils.js';
-export async function createMailbox(flags) {
+import { pollJob } from '../utils.js';
+import { requireOrg } from '../helpers.js';
+export const SCHEMA = {
+    org: 'string',
+    domain: 'string',
+    username: 'string',
+    'display-name': 'string',
+    filter: 'string',
+    address: 'string',
+    from: 'string',
+    to: 'string',
+    subject: 'string',
+    body: 'string',
+    html: 'string',
+    'template-id': 'string',
+    'template-vars': 'string',
+    limit: 'number',
+    offset: 'number',
+    prompt: 'string',
+    name: 'string',
+    emails: 'string',
+    'per-day': 'number',
+};
+// ─── Mailbox ─────────────────────────────────────────────────────────────────
+async function mailboxCreate(addressArg, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    const domain = flags.domain || config.default_domain;
-    if (!orgId || !domain || !flags.username) {
-        error("Missing required arguments.\nUsage: myapi email create-mailbox --org <id> --domain <domain> --username <user>\n(Or set defaults via: myapi config set-org <id> / set-domain <domain>)");
+    // Convention: first required arg is positional. For mailboxes that's the
+    // full address `user@domain`. The flag form (--username + --domain) is
+    // still accepted for back-compat / scripts that built up parts separately.
+    let username = flags.username;
+    let domain = flags.domain || config.default_domain;
+    if (addressArg) {
+        const at = addressArg.indexOf('@');
+        if (at > 0 && at < addressArg.length - 1) {
+            username = addressArg.slice(0, at);
+            domain = addressArg.slice(at + 1);
+        }
+        else {
+            error(`"${addressArg}" is not a valid email address. Expected format: user@domain.com`);
+        }
     }
-    const address = await sdkEmail.createMailbox(config.api_key, orgId, domain, flags.username);
-    success(`Mailbox created: ${address.address}`);
+    if (!username || !domain) {
+        error('Missing required arguments.\nUsage: myapi email mailbox create <user@domain> [--display-name <name>]\n   or: myapi email mailbox create --username <u> --domain <d> [--display-name <name>]\n(Or set default: myapi config set-domain <domain>)');
+    }
+    const res = await sdkEmail.createMailbox(config.api_key, domain, username, flags['display-name']);
+    // Backend response sometimes omits address; we know it from the inputs.
+    success(`Mailbox created: ${res.address || `${username}@${domain}`}`);
 }
-export async function listMailboxes(flags) {
+async function mailboxList(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi email list-mailboxes --org <id> [--domain <domain> | --filter unassigned]\n(Or set a default org via: myapi config set-org <id>)");
-    if (!flags.domain && flags.filter !== 'unassigned')
-        error("Must provide either --domain <domain> or --filter unassigned");
-    const mailboxes = await sdkEmail.listMailboxes(config.api_key, orgId, {
+    if (!flags.domain && flags.filter !== 'unassigned') {
+        error('Must provide either --domain <domain> (mailboxes on that domain) or --filter unassigned (mailboxes whose domain is not assigned to any org).');
+    }
+    const mailboxes = await sdkEmail.listMailboxes(config.api_key, {
         domain: flags.domain,
-        filter: flags.filter === 'unassigned' ? 'unassigned' : undefined
+        filter: flags.filter === 'unassigned' ? 'unassigned' : undefined,
+    });
+    printTable(mailboxes, {
+        flags,
+        empty: 'No mailboxes found.',
     });
-    printTable(mailboxes);
 }
-export async function sent(flags) {
+async function mailboxActivateSending(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi email sent --org <id> [--limit <num>] [--offset <num>]\n(Or set defaults via: myapi config set-org <id>)");
-    const limit = parseInt(flags.limit) || 50;
-    const offset = parseInt(flags.offset) || 0;
-    const emails = await sdkEmail.getSentEmails(config.api_key, orgId, limit, offset);
-    printTable(emails);
+    const address = flags.address;
+    if (!address)
+        error('Missing required arguments.\nUsage: myapi email mailbox activate-sending --address <email>');
+    const res = await sdkEmail.activateSending(config.api_key, address);
+    success(`Sending activated: ${address} (status: ${res.status})`);
 }
-export async function send(flags) {
+const MAILBOX_USAGE = {
+    'create': `myapi email mailbox create <user@domain> [--display-name <name>]
+       myapi email mailbox create --username <u> --domain <d> [--display-name <name>]
+
+Either form works. The positional address is the recommended shape and
+matches the rest of the CLI ("first required arg is positional").`,
+    'list': `myapi email mailbox list (--domain <domain> | --filter unassigned)
+
+  --domain <domain>     List mailboxes on the given domain.
+  --filter unassigned   List mailboxes whose domain is NOT assigned to any
+                        org (orphaned mailboxes — domain was unassigned
+                        without first deleting them).`,
+    'activate-sending': 'myapi email mailbox activate-sending --address <email>',
+};
+async function mailboxRun(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info(`Usage: myapi email mailbox <subcommand>
+
+Subcommands:
+  create             Create a mailbox (positional <user@domain> or --username/--domain)
+  list               List mailboxes on a domain (--domain) or orphaned ones (--filter unassigned)
+  activate-sending   Activate outbound sending for a mailbox`);
+        return;
+    }
+    if (flags.help) {
+        const usage = MAILBOX_USAGE[sub];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${sub}. Run "myapi email mailbox --help" for the list.`);
+        return;
+    }
+    switch (sub) {
+        case 'create': return mailboxCreate(args[0], flags);
+        case 'list': return mailboxList(flags);
+        case 'activate-sending': return mailboxActivateSending(flags);
+        default: error(`Unknown subcommand: ${sub}. Run "myapi email mailbox --help" for the list.`);
+    }
+}
+// ─── Message ─────────────────────────────────────────────────────────────────
+async function messageSend(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !flags.from || !flags.to || !flags.subject) {
-        error("Missing required arguments.\nUsage: myapi email send --org <id> --from <email> --to <email> --subject <str> [--body <str> | --template-id <id> [--template-vars <json_str>]]");
+    if (!flags.from || !flags.to || !flags.subject) {
+        error('Missing required arguments.\nUsage: myapi email message send --from <email> --to <email> --subject <str> [--body <str> | --html <str> | --template-id <id> [--template-vars <json>]]');
     }
-    if (!flags.body && !flags['template-id'])
-        error("Must provide either --body or --template-id");
-    if (flags.body && flags['template-id'])
-        error("Cannot provide both --body and --template-id");
+    if (!flags.body && !flags.html && !flags['template-id'])
+        error('Must provide one of --body, --html, or --template-id');
+    if ((flags.body || flags.html) && flags['template-id'])
+        error('Cannot combine --body/--html with --template-id');
     let templateVars;
     if (flags['template-vars']) {
         try {
             templateVars = JSON.parse(flags['template-vars']);
         }
-        catch (e) {
-            error("--template-vars must be a valid JSON string");
+        catch {
+            error('--template-vars must be valid JSON');
         }
     }
-    const res = await sdkEmail.sendEmail(config.api_key, orgId, {
+    const res = await sdkEmail.sendEmail(config.api_key, {
         from: flags.from,
         to: [flags.to],
         subject: flags.subject,
         text: flags.body,
+        html: flags.html,
         template_id: flags['template-id'],
-        template_vars: templateVars
+        template_vars: templateVars,
     });
     success(`Email sent! Message ID: ${res.message_id}`);
 }
-export async function inbox(address, flags) {
+async function messageStatus(messageId, _flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !address)
-        error("Missing required arguments.\nUsage: myapi email inbox <address> --org <id>");
-    const messages = await sdkEmail.getInbox(config.api_key, orgId, address);
-    printTable(messages);
+    if (!messageId)
+        error('Missing required arguments.\nUsage: myapi email message status <message_id>');
+    const res = await sdkEmail.getEmailStatus(config.api_key, messageId);
+    printJson(res);
 }
-export async function outbox(address, flags) {
+async function messageSent(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !address)
-        error("Missing required arguments.\nUsage: myapi email outbox <address> --org <id>");
-    const messages = await sdkEmail.getOutbox(config.api_key, orgId, address);
-    printTable(messages);
+    const limit = flags.limit || 50;
+    const offset = flags.offset || 0;
+    const emails = await sdkEmail.getSentEmails(config.api_key, limit, offset);
+    printTable(emails, {
+        flags,
+        empty: 'No sent emails yet.',
+    });
+}
+async function messageInbox(address, flags) {
+    const config = requireConfig();
+    if (!address)
+        error('Missing required arguments.\nUsage: myapi email message inbox <address>');
+    const messages = await sdkEmail.getInbox(config.api_key, address);
+    printTable(messages, {
+        flags,
+        empty: `No messages in ${address}.`,
+    });
+}
+async function messageOutbox(address, flags) {
+    const config = requireConfig();
+    if (!address)
+        error('Missing required arguments.\nUsage: myapi email message outbox <address>');
+    const messages = await sdkEmail.getOutbox(config.api_key, address);
+    printTable(messages, {
+        flags,
+        empty: `No outbound messages from ${address}.`,
+    });
+}
+async function messageGet(messageId, flags) {
+    const config = requireConfig();
+    if (!messageId || !flags.address)
+        error('Missing required arguments.\nUsage: myapi email message get <message_id> --address <email>');
+    const res = await sdkEmail.getMessage(config.api_key, messageId, flags.address);
+    printJson(res);
+}
+const MESSAGE_USAGE = {
+    'send': 'myapi email message send --from <email> --to <email> --subject <str> [--body <str> | --html <str> | --template-id <id> [--template-vars <json>]]',
+    'status': 'myapi email message status <message_id>',
+    'sent': 'myapi email message sent [--limit <n>] [--offset <n>]',
+    'inbox': 'myapi email message inbox <address>',
+    'outbox': 'myapi email message outbox <address>',
+    'get': 'myapi email message get <message_id> --address <email>',
+};
+async function messageRun(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info(`Usage: myapi email message <subcommand>
+
+Subcommands:
+  send                Send an email (transactional or templated)
+  status <id>         Get delivery status of a sent message
+  sent                List sent emails
+  inbox <addr>        Read inbox for a mailbox address
+  outbox <addr>       Read outbox for a mailbox address
+  get <id>            Get a single message (--address <email>)`);
+        return;
+    }
+    if (flags.help) {
+        const usage = MESSAGE_USAGE[sub];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${sub}. Run "myapi email message --help" for the list.`);
+        return;
+    }
+    switch (sub) {
+        case 'send': return messageSend(flags);
+        case 'status': return messageStatus(args[0], flags);
+        case 'sent': return messageSent(flags);
+        case 'inbox': return messageInbox(args[0], flags);
+        case 'outbox': return messageOutbox(args[0], flags);
+        case 'get': return messageGet(args[0], flags);
+        default: error(`Unknown subcommand: ${sub}. Run "myapi email message --help" for the list.`);
+    }
+}
+// ─── Warmup ──────────────────────────────────────────────────────────────────
+async function warmupRun(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info('Usage: myapi email warmup <start|pause|resume|stop|stats> --address <email>');
+        return;
+    }
+    if (flags.help) {
+        info(`Usage: myapi email warmup ${sub} --address <email>`);
+        return;
+    }
+    const config = requireConfig();
+    const address = flags.address || args[0];
+    if (!address)
+        error('Missing required argument: --address <email>');
+    switch (sub) {
+        case 'start': {
+            const res = await sdkEmail.startWarmup(config.api_key, address);
+            success(`Warmup started: ${address} (${res.warmup_status})`);
+            return;
+        }
+        case 'pause':
+            await sdkEmail.pauseWarmup(config.api_key, address);
+            success(`Warmup paused: ${address}`);
+            return;
+        case 'resume':
+            await sdkEmail.resumeWarmup(config.api_key, address);
+            success(`Warmup resumed: ${address}`);
+            return;
+        case 'stop':
+            await sdkEmail.stopWarmup(config.api_key, address);
+            success(`Warmup stopped: ${address}`);
+            return;
+        case 'stats': {
+            const res = await sdkEmail.getWarmupStats(config.api_key, address);
+            printJson(res);
+            return;
+        }
+        default:
+            error(`Unknown warmup subcommand: ${sub}. Use start|pause|resume|stop|stats`);
+    }
+}
+// ─── Templates ───────────────────────────────────────────────────────────────
+async function templateGenerate(nameArg, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email template generate <name> --prompt <str> [--org <id>]');
+    const name = nameArg || flags.name;
+    if (!name || !flags.prompt) {
+        error('Missing required arguments.\nUsage: myapi email template generate <name> --prompt <str> [--org <id>]\n   or: myapi email template generate --name <name> --prompt <str> [--org <id>]');
+    }
+    const job = await sdkEmail.generateTemplate(config.api_key, orgId, {
+        prompt: flags.prompt,
+        name,
+    });
+    const status = await pollJob({
+        label: 'Generating template',
+        timeoutMs: 90_000,
+        intervalMs: 3000,
+        check: () => sdkEmail.getTemplateJobStatus(config.api_key, orgId, job.job_id),
+        isDone: s => s.status === 'completed',
+        isFailed: s => s.status === 'failed',
+        failedMessage: 'Template generation failed',
+        timeoutMessage: 'Template generation timed out',
+    });
+    success(`Template generated! ID: ${status.template_id}\nPreview: ${status.result?.preview_url}`);
 }
-export async function listTemplates(flags) {
+async function templateList(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi email list-templates --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi email template list [--org <id>]');
     const templates = await sdkEmail.listTemplates(config.api_key, orgId);
-    if (flags.json)
+    if (flags.json) {
         printJson(templates);
-    else
-        printTable(templates);
+        return;
+    }
+    printTable(templates, {
+        flags,
+        empty: 'No templates yet. Generate one with: myapi email template generate --prompt <p> --name <n>',
+    });
 }
-export async function deleteTemplate(id, flags) {
+async function templateEdit(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi email delete-template <id> --org <id>\n(Or set defaults via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi email template edit <id> --prompt <str> [--org <id>]');
+    if (!id || !flags.prompt)
+        error('Missing required arguments.\nUsage: myapi email template edit <id> --prompt <str> [--org <id>]');
+    const res = await sdkEmail.editTemplate(config.api_key, orgId, id, flags.prompt);
+    success(`Template ${res.template_id} edited\nPreview: ${res.preview_url}`);
+}
+async function templateSendTest(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email template send-test <template_id> --to <email> [--org <id>]');
+    if (!id || !flags.to)
+        error('Missing required arguments.\nUsage: myapi email template send-test <template_id> --to <email> [--org <id>]');
+    const res = await sdkEmail.sendTestEmail(config.api_key, orgId, id, flags.to);
+    success(`Test sent! Message ID: ${res.message_id}`);
+}
+async function templateDelete(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email template delete <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email template delete <id> [--org <id>]');
     await sdkEmail.deleteTemplate(config.api_key, orgId, id);
     success(`Deleted template ${id}`);
 }
-export async function generateTemplate(flags) {
+const TEMPLATE_USAGE = {
+    'generate': `myapi email template generate <name> --prompt <str> [--org <id>]
+       myapi email template generate --name <name> --prompt <str> [--org <id>]
+
+Either form works; the positional name is the recommended shape.`,
+    'list': 'myapi email template list [--org <id>] [--json]',
+    'edit': 'myapi email template edit <id> --prompt <str> [--org <id>]',
+    'send-test': 'myapi email template send-test <template_id> --to <email> [--org <id>]',
+    'delete': 'myapi email template delete <id> [--org <id>]',
+};
+async function templateRun(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info(`Usage: myapi email template <subcommand>
+
+Subcommands:
+  generate <name>    Generate AI template (--prompt)
+  list               List templates
+  edit <id>          Edit a template via prompt
+  send-test <id>     Send a test email for a template (--to)
+  delete <id>        Delete a template
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
+        return;
+    }
+    if (flags.help) {
+        const usage = TEMPLATE_USAGE[sub];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${sub}. Run "myapi email template --help" for the list.`);
+        return;
+    }
+    switch (sub) {
+        case 'generate': return templateGenerate(args[0], flags);
+        case 'list': return templateList(flags);
+        case 'edit': return templateEdit(args[0], flags);
+        case 'send-test': return templateSendTest(args[0], flags);
+        case 'delete': return templateDelete(args[0], flags);
+        default: error(`Unknown subcommand: ${sub}. Run "myapi email template --help" for the list.`);
+    }
+}
+// ─── Campaigns ───────────────────────────────────────────────────────────────
+async function campaignCreate(nameArg, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !flags.prompt || !flags.name) {
-        error("Missing required arguments.\nUsage: myapi email generate-template --org <id> --prompt <str> --name <str>");
+    const orgId = requireOrg(flags, config, 'myapi email campaign create <name> --template-id <id> --from <email> [--per-day <n>] [--org <id>]');
+    const name = nameArg || flags.name;
+    if (!name || !flags['template-id'] || !flags.from) {
+        error('Missing required arguments.\nUsage: myapi email campaign create <name> --template-id <id> --from <email> [--per-day <n>] [--org <id>]\n   or: myapi email campaign create --name <name> --template-id <id> --from <email> [--per-day <n>] [--org <id>]');
     }
-    const job = await sdkEmail.generateTemplate(config.api_key, orgId, {
-        prompt: flags.prompt,
-        name: flags.name
+    const perDayLimit = flags['per-day'];
+    const res = await sdkEmail.createCampaign(config.api_key, orgId, {
+        name,
+        template_id: flags['template-id'],
+        from_address: flags.from,
+        per_day_limit: perDayLimit,
     });
-    process.stdout.write("Generating template ");
-    const chars = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-    let i = 0;
-    let elapsed = 0;
-    while (elapsed < 90000) {
-        const status = await sdkEmail.getTemplateJobStatus(config.api_key, orgId, job.job_id);
-        if (status.status === 'completed') {
-            process.stdout.write('\r\x1b[K');
-            success(`Template generated! ID: ${status.template_id}\nPreview: ${status.result?.preview_url}`);
-            return;
-        }
-        if (status.status === 'failed') {
-            process.stdout.write('\r\x1b[K');
-            error("Template generation failed");
-        }
-        process.stdout.write(`\rGenerating template ${chars[i++ % chars.length]}`);
-        await sleep(3000);
-        elapsed += 3000;
-    }
-    process.stdout.write('\r\x1b[K');
-    error("Template generation timed out");
+    success(`Campaign created! ID: ${res.id}`);
 }
-export async function listCampaigns(flags) {
+async function campaignList(flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId)
-        error("Missing required arguments.\nUsage: myapi email list-campaigns --org <id>\n(Or set a default org via: myapi config set-org <id>)");
+    const orgId = requireOrg(flags, config, 'myapi email campaign list [--org <id>]');
     const campaigns = await sdkEmail.listCampaigns(config.api_key, orgId);
-    printTable(campaigns);
+    printTable(campaigns, {
+        flags,
+        empty: 'No campaigns yet. Create one with: myapi email campaign create',
+    });
+}
+async function campaignGet(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign get <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign get <id> [--org <id>]');
+    const c = await sdkEmail.getCampaign(config.api_key, orgId, id);
+    printJson(c);
 }
-export async function campaignStats(id, flags) {
+async function campaignUpdate(id, flags) {
     const config = requireConfig();
-    const orgId = flags.org || config.default_org;
-    if (!orgId || !id)
-        error("Missing required arguments.\nUsage: myapi email campaign-stats <id> --org <id>");
+    const orgId = requireOrg(flags, config, 'myapi email campaign update <id> [--name <str>] [--per-day <n>] [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign update <id> [--name <str>] [--per-day <n>] [--org <id>]');
+    const payload = {};
+    if (flags.name)
+        payload.name = flags.name;
+    if (flags['per-day'])
+        payload.per_day_limit = flags['per-day'];
+    if (!payload.name && payload.per_day_limit === undefined) {
+        error('Nothing to update. Pass at least one of --name, --per-day.');
+    }
+    const res = await sdkEmail.updateCampaign(config.api_key, orgId, id, payload);
+    success(`Campaign ${res.id} updated`);
+}
+async function campaignUploadContacts(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign upload-contacts <campaign_id> --emails <a@x,b@y> [--org <id>]');
+    if (!id || !flags.emails) {
+        error('Missing required arguments.\nUsage: myapi email campaign upload-contacts <campaign_id> --emails <a@x,b@y> [--org <id>]');
+    }
+    const emails = flags.emails.split(',').map(s => s.trim()).filter(Boolean);
+    const res = await sdkEmail.uploadContactList(config.api_key, orgId, id, emails);
+    success(`Uploaded ${res.total} contacts (status: ${res.status})`);
+}
+async function campaignStart(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign start <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign start <id> [--org <id>]');
+    const status = await sdkEmail.getContactUploadStatus(config.api_key, orgId, id);
+    if (status.upload_status !== 'ready') {
+        error(`Contacts not ready (current status: ${status.upload_status})`);
+    }
+    const res = await sdkEmail.startCampaign(config.api_key, orgId, id);
+    success(`Campaign started (status: ${res.status})`);
+}
+async function campaignPause(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign pause <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign pause <id> [--org <id>]');
+    await sdkEmail.pauseCampaign(config.api_key, orgId, id);
+    success(`Campaign ${id} paused`);
+}
+async function campaignResume(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign resume <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign resume <id> [--org <id>]');
+    await sdkEmail.resumeCampaign(config.api_key, orgId, id);
+    success(`Campaign ${id} resumed`);
+}
+async function campaignStats(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign stats <id> [--org <id>]');
+    if (!id)
+        error('Missing required arguments.\nUsage: myapi email campaign stats <id> [--org <id>]');
     const stats = await sdkEmail.getCampaignStats(config.api_key, orgId, id);
     printJson(stats);
 }
-export async function run(subcommand, args, flags) {
-    if (!subcommand || (flags.help && !subcommand)) {
-        info('Usage: myapi email <subcommand>\n\nSubcommands:\n  create-mailbox      Create a new mailbox\n  list-mailboxes      List mailboxes\n  send                Send an email\n  sent                List sent emails\n  inbox               Read received emails\n  outbox              Read sent emails for address\n  list-templates      List email templates\n  generate-template   Generate AI template\n  delete-template     Delete a template\n  list-campaigns      List campaigns\n  campaign-stats      Get campaign stats\n\nNote: All email commands require the --org <id> flag.');
+const CAMPAIGN_USAGE = {
+    'create': `myapi email campaign create <name> --template-id <id> --from <email> [--per-day <n>] [--org <id>]
+       myapi email campaign create --name <name> --template-id <id> --from <email> [--per-day <n>] [--org <id>]
+
+Either form works; the positional name is the recommended shape.`,
+    'list': 'myapi email campaign list [--org <id>]',
+    'get': 'myapi email campaign get <id> [--org <id>]',
+    'update': 'myapi email campaign update <id> [--name <str>] [--per-day <n>] [--org <id>]',
+    'upload-contacts': 'myapi email campaign upload-contacts <campaign_id> --emails <a@x,b@y> [--org <id>]',
+    'start': 'myapi email campaign start <id> [--org <id>]',
+    'pause': 'myapi email campaign pause <id> [--org <id>]',
+    'resume': 'myapi email campaign resume <id> [--org <id>]',
+    'stats': 'myapi email campaign stats <id> [--org <id>]',
+};
+async function campaignRun(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info(`Usage: myapi email campaign <subcommand>
+
+Subcommands:
+  create <name>       Create a campaign (--template-id --from)
+  list                List campaigns
+  get <id>            Get a single campaign
+  update <id>         Patch name / per-day-limit
+  upload-contacts <id>  Upload contact list (--emails a@x,b@y)
+  start <id>          Start a campaign
+  pause <id>          Pause a campaign
+  resume <id>         Resume a campaign
+  stats <id>          Get campaign stats
+
+All commands accept --org <id> (or set default: myapi config set-org <id>).`);
         return;
     }
     if (flags.help) {
-        if (subcommand === 'create-mailbox')
-            info('Usage: myapi email create-mailbox --org <id> --domain <domain> --username <user>');
-        else if (subcommand === 'list-mailboxes')
-            info('Usage: myapi email list-mailboxes --org <id> [--domain <domain> | --filter unassigned]');
-        else if (subcommand === 'send')
-            info('Usage: myapi email send --org <id> --from <email> --to <email> --subject <str> [--body <str> | --template-id <id> [--template-vars <json_str>]]');
-        else if (subcommand === 'sent')
-            info('Usage: myapi email sent --org <id> [--limit <num>] [--offset <num>]');
-        else if (subcommand === 'inbox')
-            info('Usage: myapi email inbox <address> --org <id>');
-        else if (subcommand === 'outbox')
-            info('Usage: myapi email outbox <address> --org <id>');
-        else if (subcommand === 'list-templates')
-            info('Usage: myapi email list-templates --org <id>');
-        else if (subcommand === 'generate-template')
-            info('Usage: myapi email generate-template --org <id> --prompt <str> --name <str>');
-        else if (subcommand === 'delete-template')
-            info('Usage: myapi email delete-template <id> --org <id>');
-        else if (subcommand === 'list-campaigns')
-            info('Usage: myapi email list-campaigns --org <id>');
-        else if (subcommand === 'campaign-stats')
-            info('Usage: myapi email campaign-stats <campaign_id> --org <id>');
+        const usage = CAMPAIGN_USAGE[sub];
+        if (usage)
+            info(`Usage: ${usage}`);
+        else
+            info(`Unknown subcommand: ${sub}. Run "myapi email campaign --help" for the list.`);
+        return;
+    }
+    switch (sub) {
+        case 'create': return campaignCreate(args[0], flags);
+        case 'list': return campaignList(flags);
+        case 'get': return campaignGet(args[0], flags);
+        case 'update': return campaignUpdate(args[0], flags);
+        case 'upload-contacts': return campaignUploadContacts(args[0], flags);
+        case 'start': return campaignStart(args[0], flags);
+        case 'pause': return campaignPause(args[0], flags);
+        case 'resume': return campaignResume(args[0], flags);
+        case 'stats': return campaignStats(args[0], flags);
+        default: error(`Unknown subcommand: ${sub}. Run "myapi email campaign --help" for the list.`);
+    }
+}
+// ─── Deprecated flat aliases ─────────────────────────────────────────────────
+// Old subcommand → new namespace + sub. Kept so existing scripts/skills don't
+// break. Emits a one-line stderr deprecation note then runs the new path.
+const DEPRECATED_ALIASES = {
+    'create-mailbox': ['mailbox', 'create'],
+    'list-mailboxes': ['mailbox', 'list'],
+    'activate-sending': ['mailbox', 'activate-sending'],
+    'send': ['message', 'send'],
+    'get-status': ['message', 'status'],
+    'sent': ['message', 'sent'],
+    'inbox': ['message', 'inbox'],
+    'outbox': ['message', 'outbox'],
+    'get-message': ['message', 'get'],
+    'generate-template': ['template', 'generate'],
+    'list-templates': ['template', 'list'],
+    'edit-template': ['template', 'edit'],
+    'send-test': ['template', 'send-test'],
+    'delete-template': ['template', 'delete'],
+    'create-campaign': ['campaign', 'create'],
+    'list-campaigns': ['campaign', 'list'],
+    'get-campaign': ['campaign', 'get'],
+    'update-campaign': ['campaign', 'update'],
+    'upload-contacts': ['campaign', 'upload-contacts'],
+    'start-campaign': ['campaign', 'start'],
+    'pause-campaign': ['campaign', 'pause'],
+    'resume-campaign': ['campaign', 'resume'],
+    'campaign-stats': ['campaign', 'stats'],
+};
+// ─── Top-level dispatcher ────────────────────────────────────────────────────
+export async function run(subcommand, args, flags) {
+    if (!subcommand || (flags.help && !subcommand)) {
+        info(`Usage: myapi email <namespace> <subcommand>
+
+Namespaces:
+  mailbox    Mailboxes (account-scoped) — create, list, activate-sending
+  message    Send & read mail (account-scoped) — send, status, sent, inbox, outbox, get
+  warmup     Warmup controls (account-scoped) — start, pause, resume, stop, stats
+  template   Email templates (org-scoped) — generate, list, edit, send-test, delete
+  campaign   Email campaigns (org-scoped) — create, list, get, update, upload-contacts, start, pause, resume, stats
+
+Examples:
+  myapi email mailbox create --domain example.com --username hello
+  myapi email message send --from a@x --to b@y --subject hi --body "hello"
+  myapi email template generate --prompt "Welcome email" --name welcome
+  myapi email campaign create --name "Q2 Launch" --template-id <id> --from a@x
+
+Org-scoped commands accept --org <id> (or set default: myapi config set-org <id>).
+Run "myapi email <namespace> --help" for namespace-specific commands.`);
         return;
     }
-    if (subcommand === 'create-mailbox')
-        await createMailbox(flags);
-    else if (subcommand === 'list-mailboxes')
-        await listMailboxes(flags);
-    else if (subcommand === 'send')
-        await send(flags);
-    else if (subcommand === 'sent')
-        await sent(flags);
-    else if (subcommand === 'inbox')
-        await inbox(args[0], flags);
-    else if (subcommand === 'outbox')
-        await outbox(args[0], flags);
-    else if (subcommand === 'list-templates')
-        await listTemplates(flags);
-    else if (subcommand === 'generate-template')
-        await generateTemplate(flags);
-    else if (subcommand === 'delete-template')
-        await deleteTemplate(args[0], flags);
-    else if (subcommand === 'list-campaigns')
-        await listCampaigns(flags);
-    else if (subcommand === 'campaign-stats')
-        await campaignStats(args[0], flags);
-    else
-        error(`Unknown subcommand: ${subcommand}. Run "myapi email --help" for a list of valid subcommands.`);
+    // Deprecated flat command? Forward to the new path with a one-line note.
+    const aliased = DEPRECATED_ALIASES[subcommand];
+    if (aliased) {
+        const [ns, sub] = aliased;
+        process.stderr.write(`› Note: "email ${subcommand}" is deprecated — use "email ${ns} ${sub}" instead.\n`);
+        return dispatchNamespace(ns, sub, args, flags);
+    }
+    return dispatchNamespace(subcommand, args[0], args.slice(1), flags);
+}
+async function dispatchNamespace(ns, sub, restArgs, flags) {
+    switch (ns) {
+        case 'mailbox': return mailboxRun(sub, restArgs, flags);
+        case 'message': return messageRun(sub, restArgs, flags);
+        case 'warmup': return warmupRun(sub, restArgs, flags);
+        case 'template': return templateRun(sub, restArgs, flags);
+        case 'campaign': return campaignRun(sub, restArgs, flags);
+        default: error(`Unknown namespace: ${ns}. Run "myapi email --help" for the list.`);
+    }
 }