@myapihq/cli 2.21.0 → 2.22.0

package/dist/commands/account.d.ts

@@ -3,7 +3,7 @@ import type { Flags } from '../helpers.js';
 import type { Exposes } from '../exposes.js';
 export declare const EXPOSES: Exposes;
 export declare const SCHEMA: FlagSchema;
-export declare const HELP = "Usage: myapi account <subcommand>\n\nSubcommands:\n  api-keys        Manage API keys \u00B7 list / create / revoke\n  config          Manage CLI defaults (org, funnel, domain) \u00B7 supports set-org / set-funnel / set-domain\n  import-key      Import an existing API key non-interactively\n  install-skills  DEPRECATED \u2014 use `myapi install-skills` instead\n  keys            Alias for api-keys\n  link [email]    Upgrade anonymous account to registered (or add a second session)\n                  Use myapi account setup to create a completely new account\n  login           Sign in via your browser \u2014 Google or email code (preview: --mock)\n  mailing-address Get or set the account's mailing address (CAN-SPAM)\n  registrant      Manage stored WHOIS contact info for domain registration \u00B7 set / get / clear\n  setup           Configure your account\n  switch [index]  Switch active account by index or email\n  whoami          Show current account \u00B7 supports --json";
+export declare const HELP = "Usage: myapi account <subcommand>\n\nSubcommands:\n  api-keys        Manage API keys \u00B7 list / create / revoke\n  config          Manage CLI defaults (org, funnel, domain) \u00B7 supports set-org / set-funnel / set-domain\n  import-key      Import an existing API key non-interactively\n  install-skills  DEPRECATED \u2014 use `myapi install-skills` instead\n  keys            Alias for api-keys\n  link [email]    Upgrade anonymous account to registered (or add a second session)\n                  Use myapi account setup to create a completely new account\n  login           Sign in via your browser \u2014 Google or email code (preview: --mock)\n  mailing-address Get or set the account's mailing address (CAN-SPAM)\n  registrant      Manage stored WHOIS contact info for domain registration \u00B7 set / get / clear\n  resume-sending  Turn email sending back on after an automatic pause\n  sending         Whether this account can send email, and how close it is to the limits\n  setup           Configure your account\n  switch [index]  Switch active account by index or email\n  whoami          Show current account \u00B7 supports --json";
 export declare const INSTALL_SKILLS_HELP = "Usage: myapi install-skills\n\nInstalls the MyAPI skills pack for AI coding agents (Claude, Codex, Gemini, \u2026).\n\nThis command writes skill definition files to:\n  ~/.agents/skills/myapi/\n\nAnd creates symlinks in the appropriate agent config directories:\n  ~/.claude/  (Claude)\n  ~/.gemini/  (Gemini)\n  ~/.cursor/  (Cursor, if detected)\n\nThese files teach agents how to use the MyAPI CLI and API directly.\nRun this command again to update existing skills to the latest version.\n\nNote: `myapi account install-skills` is deprecated and will be removed in the next minor.\nUse `myapi install-skills` going forward.";
 export declare const SUBCOMMAND_USAGE: Record<string, string>;
 export declare function link(flags?: Flags, emailArg?: string): Promise<void>;

package/dist/commands/account.js

@@ -17,6 +17,8 @@ export const EXPOSES = [
     'POST /hq/account/verify-code',
     'GET /hq/billing/balance',
     'GET /hq/account/free-tier',
+    'GET /hq/account/sending',
+    'POST /hq/account/resume-sending',
     'GET /hq/account/mailing-address',
     'PATCH /hq/account/mailing-address',
 ];
@@ -54,6 +56,8 @@ Subcommands:
   login           Sign in via your browser — Google or email code (preview: --mock)
   mailing-address Get or set the account's mailing address (CAN-SPAM)
   registrant      Manage stored WHOIS contact info for domain registration · set / get / clear
+  resume-sending  Turn email sending back on after an automatic pause
+  sending         Whether this account can send email, and how close it is to the limits
   setup           Configure your account
   switch [index]  Switch active account by index or email
   whoami          Show current account · supports --json`;
@@ -116,6 +120,23 @@ Subcommands:
   set       Interactive prompt for all fields. Or pass --registrant-json
             '<json>' to set non-interactively (agent-friendly).`;
 export const SUBCOMMAND_USAGE = {
+    sending: `myapi account sending [--json]
+
+  Whether this account can send email, and how close it is to the limits.
+
+  The platform pauses sending when too much of the last 24 hours bounces.
+  The pause message is a photograph of the moment it happened — this is the
+  live picture, and the two can disagree: an account paused yesterday may be
+  well within the limits today and simply need resuming.
+
+  Under 100 sends in 24h the ratios are not judged, and the reply says so.`,
+    'resume-sending': `myapi account resume-sending [--json]
+
+  Turn sending back on after an automatic pause.
+
+  Refused with STILL_OVER_THRESHOLD while the last 24 hours are still over
+  the limit — the numbers come back with the refusal, so you can see how far
+  off you are. Removing the addresses that bounce is what moves them.`,
     'mailing-address': `myapi account mailing-address                       Show current value (null if unset)
 myapi account mailing-address "<address>"            Set the mailing address
 
@@ -410,6 +431,41 @@ async function mailingAddress(args, flags) {
     }
     success(`Mailing address set: ${res.mailing_address}`);
 }
+// The pause is invisible until a send fails, so both verbs lead with the one
+// fact that decides what to do next: can this account send right now.
+async function sendingStatus(flags) {
+    const config = requireConfig();
+    const res = await hq.getSendingStatus(config.api_key);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    info(res.sending_paused ? 'Sending is PAUSED.' : 'Sending is on.');
+    info(`Last 24h: ${res.sends_24h} sent · ${res.bounces_24h} bounced · ${res.complaints_24h} complaints`);
+    info(`Limits:   ${(res.bounce_threshold * 100).toFixed(1)}% bounces · ${(res.complaint_threshold * 100).toFixed(2)}% complaints`);
+    if (res.note)
+        info(res.note);
+    if (res.sending_paused) {
+        if (res.paused_reason_when_paused) {
+            // Labelled as history, because the live numbers above may disagree with
+            // it — and reading the frozen reason as current is the whole confusion.
+            info(`Paused because (at the time): ${res.paused_reason_when_paused}`);
+        }
+        info(res.can_resume_now
+            ? 'Within the limits now — run: myapi account resume-sending'
+            : 'Still over the limit. Remove the addresses that bounce, then resume.');
+    }
+}
+async function resumeSending(flags) {
+    const config = requireConfig();
+    const res = await hq.resumeSending(config.api_key);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    success(res.message);
+    info(`Last 24h: ${res.sends} sent · ${res.bounces} bounced`);
+}
 export async function run(subcommand, args, flags) {
     if (!subcommand || (flags.help && !subcommand)) {
         info(HELP);
@@ -424,6 +480,8 @@ export async function run(subcommand, args, flags) {
     }
     switch (subcommand) {
         case 'mailing-address': return mailingAddress(args, flags);
+        case 'sending': return sendingStatus(flags);
+        case 'resume-sending': return resumeSending(flags);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi account --help" for the list.`);
     }
 }

package/dist/commands/audience.js

@@ -2,6 +2,11 @@ import { audience as sdkAudience } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Only create/update/members/refresh gate — list, get and delete are free and stay unwrapped.
 export const EXPOSES = [
     'POST /audience/orgs/{org_id}/audiences',
     'GET /audience/orgs/{org_id}/audiences',
@@ -59,9 +64,9 @@ async function create(nameArg, flags) {
     }
     const filter = parseFilter(flags.filter);
     const description = typeof flags.description === 'string' ? flags.description : undefined;
-    const res = await sdkAudience.createAudience(config.api_key, orgId, {
+    const res = await retryFunds(() => sdkAudience.createAudience(config.api_key, orgId, {
         name, source: source, filter, description,
-    });
+    }));
     if (flags.json) {
         printJson(res);
         return;
@@ -102,7 +107,7 @@ async function update(id, flags) {
     if (Object.keys(patch).length === 0) {
         error('Pass at least one of --name / --description / --filter to update.');
     }
-    const res = await sdkAudience.updateAudience(config.api_key, orgId, id, patch);
+    const res = await retryFunds(() => sdkAudience.updateAudience(config.api_key, orgId, id, patch));
     if (flags.json) {
         printJson(res);
         return;
@@ -125,7 +130,7 @@ async function members(id, flags) {
         opts.limit = flags.limit;
     if (typeof flags.offset === 'number')
         opts.offset = flags.offset;
-    const res = await sdkAudience.getAudienceMembers(config.api_key, orgId, id, opts);
+    const res = await retryFunds(() => sdkAudience.getAudienceMembers(config.api_key, orgId, id, opts));
     if (flags.json) {
         printJson(res);
         return;
@@ -161,7 +166,7 @@ async function refresh(id, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi audience refresh <id> [--org <id>]');
     requireArg(id, 'id', 'myapi audience refresh <id> [--org <id>]');
-    const res = await sdkAudience.refreshAudience(config.api_key, orgId, id);
+    const res = await retryFunds(() => sdkAudience.refreshAudience(config.api_key, orgId, id));
     if (flags.json) {
         printJson(res);
         return;

package/dist/commands/company.js

@@ -2,6 +2,11 @@ import { company as sdkCompany } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Both handlers gate; there is no free company call.
 export const EXPOSES = [
     'POST /company/orgs/{org_id}/search',
     'GET /company/orgs/{org_id}/{company_id}',
@@ -72,7 +77,7 @@ async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi company search [filters...] [--org <id>]');
     const options = buildSearch(flags);
-    const res = await sdkCompany.searchCompanies(config.api_key, orgId, options);
+    const res = await retryFunds(() => sdkCompany.searchCompanies(config.api_key, orgId, options));
     if (flags.json) {
         printJson(res);
         return;
@@ -94,7 +99,7 @@ async function get(companyId, flags) {
     const orgId = requireOrg(flags, config, 'myapi company get <company_id> [--include-people N] [--org <id>]');
     requireArg(companyId, 'company_id', 'myapi company get <company_id> [--include-people N] [--org <id>]');
     const includePeople = typeof flags['include-people'] === 'number' ? flags['include-people'] : undefined;
-    const res = await sdkCompany.getCompany(config.api_key, orgId, companyId, includePeople);
+    const res = await retryFunds(() => sdkCompany.getCompany(config.api_key, orgId, companyId, includePeople));
     printJson(res);
 }
 export const SUBCOMMAND_USAGE = {

package/dist/commands/email/campaign.d.ts

@@ -0,0 +1,5 @@
+import { type Flags } from '../../helpers.js';
+import type { Exposes } from '../../exposes.js';
+export declare const EXPOSES: Exposes;
+export declare const HELP = "Usage: myapi email campaign <subcommand>\n\n  create      Create a draft (--template, --from, and a source)\n  list        Campaigns in this org\n  get <id>    One campaign\n  update <id> Edit a DRAFT's name or source\n  resolve <id>  Freeze who it reaches; reports the count and cost, sends nothing\n  start <id>  Begin sending a resolved campaign\n  pause <id>  Stop after the message in flight\n  resume <id> Continue a paused campaign\n  cancel <id> End it for good; queued recipients are dropped\n  recipients <id>  Who it resolved to, and what happened to each\n  stats <id>  Counts by state, sent today, and the daily limit\n\nA campaign drains at its per-day limit rather than sending at once, so it is\ncommonly still active tomorrow \u2014 that is the design, not a stall.\n\nRecipients come from a SOURCE, not a list you upload:\n  --crm-stage / --crm-origin / --crm-max-days   filter CRM contacts\n  --addresses a@x.com,b@y.com                   an explicit short list";
+export declare function run(sub: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/email/campaign.js

@@ -0,0 +1,238 @@
+import { email as sdkEmail } from '@myapihq/sdk';
+import { requireConfig } from '../../config.js';
+import { success, error, info, printTable, printJson } from '../../output.js';
+import { retryFunds } from '../../utils.js';
+import { requireOrg, requireArg } from '../../helpers.js';
+export const EXPOSES = [
+    'POST /email/orgs/{org_id}/campaigns',
+    'GET /email/orgs/{org_id}/campaigns',
+    'GET /email/orgs/{org_id}/campaigns/{campaign_id}',
+    'PATCH /email/orgs/{org_id}/campaigns/{campaign_id}',
+    'POST /email/orgs/{org_id}/campaigns/{campaign_id}/resolve',
+    'POST /email/orgs/{org_id}/campaigns/{campaign_id}/start',
+    'POST /email/orgs/{org_id}/campaigns/{campaign_id}/pause',
+    'POST /email/orgs/{org_id}/campaigns/{campaign_id}/resume',
+    'POST /email/orgs/{org_id}/campaigns/{campaign_id}/cancel',
+    'GET /email/orgs/{org_id}/campaigns/{campaign_id}/recipients',
+    'GET /email/orgs/{org_id}/campaigns/{campaign_id}/stats',
+];
+export const HELP = `Usage: myapi email campaign <subcommand>
+
+  create      Create a draft (--template, --from, and a source)
+  list        Campaigns in this org
+  get <id>    One campaign
+  update <id> Edit a DRAFT's name or source
+  resolve <id>  Freeze who it reaches; reports the count and cost, sends nothing
+  start <id>  Begin sending a resolved campaign
+  pause <id>  Stop after the message in flight
+  resume <id> Continue a paused campaign
+  cancel <id> End it for good; queued recipients are dropped
+  recipients <id>  Who it resolved to, and what happened to each
+  stats <id>  Counts by state, sent today, and the daily limit
+
+A campaign drains at its per-day limit rather than sending at once, so it is
+commonly still active tomorrow — that is the design, not a stall.
+
+Recipients come from a SOURCE, not a list you upload:
+  --crm-stage / --crm-origin / --crm-max-days   filter CRM contacts
+  --addresses a@x.com,b@y.com                   an explicit short list`;
+// Building the source from flags is the one place the CLI has an opinion: a
+// campaign names where its people come from, and mixing two sources in one
+// command is a request nobody can mean.
+function sourceFromFlags(flags) {
+    const addrs = typeof flags.addresses === 'string' && flags.addresses
+        ? flags.addresses.split(',').map(s => s.trim()).filter(Boolean)
+        : [];
+    const crm = {};
+    if (typeof flags['crm-stage'] === 'string' && flags['crm-stage'])
+        crm.stage = flags['crm-stage'];
+    if (typeof flags['crm-origin'] === 'string' && flags['crm-origin'])
+        crm.origin = flags['crm-origin'];
+    if (typeof flags['crm-company'] === 'string' && flags['crm-company'])
+        crm.company_id = flags['crm-company'];
+    if (typeof flags['crm-max-days'] === 'number')
+        crm.max_last_engagement_days = flags['crm-max-days'];
+    if (typeof flags['crm-min-days'] === 'number')
+        crm.min_last_engagement_days = flags['crm-min-days'];
+    const hasCRM = Object.keys(crm).length > 0;
+    if (addrs.length && hasCRM) {
+        error('Pass either --addresses or the --crm-* filters, not both — a campaign draws from one source.');
+    }
+    if (addrs.length)
+        return { source_kind: 'list', source_ref: { addresses: addrs } };
+    if (hasCRM)
+        return { source_kind: 'crm_query', source_ref: crm };
+    // An unfiltered CRM query is every contact in the org. That is a legitimate
+    // campaign and a very easy accident, so it has to be asked for by name.
+    if (flags['all-contacts'])
+        return { source_kind: 'crm_query', source_ref: {} };
+    error('No source. Use --addresses <csv>, a --crm-* filter, or --all-contacts to mean every CRM contact.');
+    throw new Error('unreachable');
+}
+function fmtCents(c) {
+    if (c == null)
+        return '—';
+    return c < 100 ? `${c.toFixed(2)}¢` : `$${(c / 100).toFixed(2)}`;
+}
+async function create(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign create --name <n> --template <id> --from <addr> [--addresses <csv> | --crm-stage <s>]');
+    const name = typeof flags.name === 'string' ? flags.name : '';
+    const template = typeof flags.template === 'string' ? flags.template : '';
+    const from = typeof flags.from === 'string' ? flags.from : '';
+    if (!name || !template || !from) {
+        error('Missing required flags: --name, --template <template-id>, --from <mailbox address>.');
+    }
+    const src = sourceFromFlags(flags);
+    const c = await sdkEmail.createCampaign(config.api_key, orgId, {
+        name, template_id: template, from_address: from, ...src,
+    });
+    if (flags.json) {
+        printJson(c);
+        return;
+    }
+    success(`Draft campaign ${c.id}`);
+    info(`Next: myapi email campaign resolve ${c.id}   # who it reaches and what it costs — sends nothing`);
+}
+async function list(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign list [--org <id>]');
+    const rows = await sdkEmail.listCampaigns(config.api_key, orgId);
+    if (flags.json) {
+        printJson(rows);
+        return;
+    }
+    printTable(rows.map(c => ({
+        id: c.id,
+        name: c.name,
+        status: c.status,
+        source: c.source_kind,
+        recipients: c.recipient_count ?? '—',
+        est: fmtCents(c.estimated_cost_cents),
+    })), { flags, empty: 'No campaigns yet. Create one with: myapi email campaign create --name ... --template ... --from ...' });
+}
+async function get(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign get <id>');
+    const c = await sdkEmail.getCampaign(config.api_key, orgId, id);
+    if (flags.json) {
+        printJson(c);
+        return;
+    }
+    info(`${c.name}  [${c.status}]`);
+    info(`from ${c.from_address} · template ${c.template_id} · source ${c.source_kind}`);
+    info(`recipients ${c.recipient_count ?? '—'} · estimated ${fmtCents(c.estimated_cost_cents)}`);
+    if (c.resolved_at)
+        info(`resolved ${c.resolved_at}`);
+}
+async function update(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign update <id> [--name <n>] [--addresses <csv>]');
+    const patch = {};
+    if (typeof flags.name === 'string' && flags.name)
+        patch.name = flags.name;
+    const wantsSource = flags.addresses || flags['crm-stage'] || flags['crm-origin']
+        || flags['crm-company'] || flags['crm-max-days'] || flags['crm-min-days'] || flags['all-contacts'];
+    if (wantsSource)
+        Object.assign(patch, sourceFromFlags(flags));
+    if (Object.keys(patch).length === 0)
+        error('Nothing to change. Pass --name or a source flag.');
+    const c = await sdkEmail.updateCampaign(config.api_key, orgId, id, patch);
+    if (flags.json) {
+        printJson(c);
+        return;
+    }
+    success(`Updated ${c.id}`);
+}
+async function resolve(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign resolve <id>');
+    const r = await sdkEmail.resolveCampaign(config.api_key, orgId, id);
+    if (flags.json) {
+        printJson(r);
+        return;
+    }
+    success(`${r.recipients} recipient(s) · estimated ${fmtCents(r.estimated_cost_cents)}`);
+    const excluded = Object.entries(r.excluded ?? {});
+    if (excluded.length) {
+        // Saying WHY the number shrank is the difference between a product and a
+        // black box — the source had more rows than this, and the caller is owed
+        // the reason.
+        info(`From ${r.source_rows} source row(s); excluded ${excluded.map(([k, n]) => `${n} ${k}`).join(', ')}.`);
+    }
+    info('Nothing has been sent. Start it with: myapi email campaign start ' + id);
+}
+async function transition(verb, id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, `myapi email campaign ${verb} <id>`);
+    const fn = {
+        start: sdkEmail.startCampaign,
+        pause: sdkEmail.pauseCampaign,
+        resume: sdkEmail.resumeCampaign,
+        cancel: sdkEmail.cancelCampaign,
+    }[verb];
+    // start is the billable one: it commits the account to the resolved cost.
+    const c = verb === 'start'
+        ? await retryFunds(() => fn(config.api_key, orgId, id))
+        : await fn(config.api_key, orgId, id);
+    if (flags.json) {
+        printJson(c);
+        return;
+    }
+    success(`${c.name} is now ${c.status}`);
+    if (verb === 'start') {
+        info(`It sends up to its daily limit and continues tomorrow — check with: myapi email campaign stats ${id}`);
+    }
+}
+async function recipients(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign recipients <id> [--state queued|sent|failed|excluded]');
+    const state = typeof flags.state === 'string' ? flags.state : undefined;
+    const rows = await sdkEmail.listCampaignRecipients(config.api_key, orgId, id, state);
+    if (flags.json) {
+        printJson(rows);
+        return;
+    }
+    printTable(rows.map(r => ({
+        address: r.address,
+        state: r.state,
+        reason: r.excluded_reason ?? r.error ?? '',
+        sent_at: r.sent_at ?? '',
+    })), { flags, empty: 'No recipients. Resolve the campaign first.' });
+}
+async function stats(id, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi email campaign stats <id>');
+    const s = await sdkEmail.getCampaignStats(config.api_key, orgId, id);
+    if (flags.json) {
+        printJson(s);
+        return;
+    }
+    info(`status ${s.status} · ${s.sent_today} sent today · limit ${s.per_day_limit}/day`);
+    const parts = Object.entries(s.by_state ?? {}).map(([k, n]) => `${n} ${k}`);
+    info(parts.length ? parts.join(' · ') : 'no recipients resolved yet');
+    if (s.status === 'paused_insufficient_funds') {
+        info('Paused because the account could not pay. Top up or enable auto-recharge, then: myapi email campaign resume ' + id);
+    }
+}
+export async function run(sub, args, flags) {
+    if (!sub || (flags.help && !sub)) {
+        info(HELP);
+        return;
+    }
+    const need = (usage) => requireArg(args[0], '<id>', usage);
+    switch (sub) {
+        case 'create': return create(flags);
+        case 'list': return list(flags);
+        case 'get': return get(need('myapi email campaign get <id>'), flags);
+        case 'update': return update(need('myapi email campaign update <id>'), flags);
+        case 'resolve': return resolve(need('myapi email campaign resolve <id>'), flags);
+        case 'start': return transition('start', need('myapi email campaign start <id>'), flags);
+        case 'pause': return transition('pause', need('myapi email campaign pause <id>'), flags);
+        case 'resume': return transition('resume', need('myapi email campaign resume <id>'), flags);
+        case 'cancel': return transition('cancel', need('myapi email campaign cancel <id>'), flags);
+        case 'recipients': return recipients(need('myapi email campaign recipients <id>'), flags);
+        case 'stats': return stats(need('myapi email campaign stats <id>'), flags);
+        default: error(`Unknown subcommand: email campaign ${sub}. Run "myapi email campaign --help".`);
+    }
+}

package/dist/commands/email/index.js

@@ -11,7 +11,18 @@ import * as message from './message.js';
 import * as warmup from './warmup.js';
 import * as template from './template.js';
 import * as verify from './verify.js';
+import * as campaign from './campaign.js';
 export const SCHEMA = {
+    // campaigns (`from` is declared below, shared with `message send`)
+    template: 'string',
+    addresses: 'string',
+    'crm-stage': 'string',
+    'crm-origin': 'string',
+    'crm-company': 'string',
+    'crm-max-days': 'number',
+    'crm-min-days': 'number',
+    'all-contacts': 'boolean',
+    state: 'string',
     org: 'string',
     domain: 'string',
     username: 'string',
@@ -60,6 +71,7 @@ async function dispatchNamespace(ns, sub, restArgs, flags) {
         case 'warmup': return warmup.run(sub, restArgs, flags);
         case 'template': return template.run(sub, restArgs, flags);
         case 'verify': return verify.run(sub, restArgs, flags);
+        case 'campaign': return campaign.run(sub, restArgs, flags);
         default: error(`Unknown namespace: ${ns}. Run "myapi email --help" for the list.`);
     }
 }
@@ -68,6 +80,7 @@ export async function run(subcommand, args, flags) {
         info(`Usage: myapi email <namespace> <subcommand>
 
 Namespaces:
+  campaign   Scheduled bulk send (org-scoped) — resolve, start, pause, stats; drains at a daily limit
   mailbox    Mailboxes (account-scoped) — create, list, activate-sending
   message    Send & read mail (account-scoped) — send, status, sent, inbox, outbox, get
   template   Email templates (org-scoped) — generate, list, edit, send-test, delete

package/dist/commands/people.js

@@ -2,6 +2,11 @@ import { people as sdkPeople } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Both handlers gate; there is no free people call.
 export const EXPOSES = [
     'POST /people/orgs/{org_id}/search',
     'GET /people/orgs/{org_id}/{person_id}',
@@ -61,7 +66,7 @@ async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi people search [filters...] [--org <id>]');
     const filter = buildFilter(flags);
-    const res = await sdkPeople.searchPeople(config.api_key, orgId, filter);
+    const res = await retryFunds(() => sdkPeople.searchPeople(config.api_key, orgId, filter));
     if (flags.json) {
         printJson(res);
         return;
@@ -80,7 +85,7 @@ async function get(personId, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi people get <person_id> [--org <id>]');
     requireArg(personId, 'person_id', 'myapi people get <person_id> [--org <id>]');
-    const res = await sdkPeople.getPerson(config.api_key, orgId, personId);
+    const res = await retryFunds(() => sdkPeople.getPerson(config.api_key, orgId, personId));
     printJson(res);
 }
 export const SUBCOMMAND_USAGE = {

package/dist/completion.js

@@ -35,7 +35,7 @@ export const COMMANDS = [
 // command → subcommands, for `myapi <command> <TAB>`. Mirrors each
 // command's dispatcher; commands absent here take no subcommand.
 export const SUBCOMMANDS = {
-    account: ['setup', 'import-key', 'whoami', 'login', 'link', 'switch', 'install-skills', 'config', 'registrant', 'api-keys', 'keys', 'mailing-address'],
+    account: ['setup', 'import-key', 'whoami', 'login', 'link', 'switch', 'install-skills', 'config', 'registrant', 'api-keys', 'keys', 'mailing-address', 'sending', 'resume-sending'],
     // The end-user auth product. Operator/account commands live under `account`.
     auth: ['tenant', 'client', 'usage', 'domain'],
     org: ['create', 'delete', 'get', 'import', 'list', 'sync-brand', 'update'],

package/dist/exposes.test.js

@@ -22,6 +22,7 @@ const COMMAND_MODULES = [
     './commands/email/template.js',
     './commands/email/warmup.js',
     './commands/email/verify.js',
+    './commands/email/campaign.js',
     './commands/funnel.js',
     './commands/image.js',
     './commands/keys.js',

package/dist/index.js

@@ -411,6 +411,8 @@ async function dispatchAccount(subcommand, restArgs, flags) {
     }
     switch (subcommand) {
         case 'mailing-address': return accountCmd.run('mailing-address', restArgs, flags);
+        case 'sending': return accountCmd.run('sending', restArgs, flags);
+        case 'resume-sending': return accountCmd.run('resume-sending', restArgs, flags);
         case 'setup': return setupCmd.setup(flags);
         case 'import-key': return setupCmd.importKey(restArgs[0], flags);
         case 'whoami': return accountCmd.whoami(flags);

package/dist/skills/my-api-hq/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-api-hq
-version: 1.2.2
+version: 1.3.0
 description: >
   Auth, organizations, and billing hub. Start here to get an api_key and org_id — every other service depends on both.
 triggers: [api key, account, organization, org, billing, balance, topup, credits, setup, defaults, brand, sync brand, doctor, health check, is my org healthy]
-checksum: sha256-e7f0a16a130603ca5664cf5c268658bffd85230fe89dc82a4fda715ff81135b8
+checksum: sha256-fd266da15b05dee12ce1e683612b76e0f5554247f255a9c8db9be006a403a8ff
 ---
 
 # MyApiHQ
@@ -26,7 +26,7 @@ An anonymous account can upgrade at any time via `myapi account link <email>`
 
 ### Health check
 
-`myapi doctor` runs an org-wide consistency check across every slot (funnels, webhooks, domains, containers, workflows, emails, payments) and layers on customer-perspective DNS/HTTP probes from your machine. It returns per-section findings (`✓` pass / `⚠` warning / `✗` critical) with remediation hints; add `--json` for machine output. The exit code is non-zero **only** on customer-actionable criticals — platform-side issues the MyAPI team is already handling are surfaced with an `ℹ` marker but don't fail the run. Run it to self-check before building (is the org set up?) and after (did everything wire up?).
+`myapi doctor` runs an org-wide consistency check across every slot and layers on customer-perspective DNS/HTTP probes from your machine. It returns per-section findings (`✓` pass / `⚠` warning / `✗` critical) with remediation hints; add `--json` for machine output. The exit code is non-zero **only** on customer-actionable criticals — platform-side issues the MyAPI team is already handling are surfaced with an `ℹ` marker but don't fail the run. Run it to self-check before building (is the org set up?) and after (did everything wire up?).
 <!-- llm:end -->
 
 ## Commands
@@ -53,6 +53,7 @@ An anonymous account can upgrade at any time via `myapi account link <email>`
 | `myapi billing usage [--period month|30d]` | Spend rolled up by service (month or trailing 30d) |
 | `myapi billing spend-cap [<amount> | clear] [--period month|day]` | Set/show/clear the account-level spend ceiling |
 | `myapi billing auto-recharge [show \| set \| disable]` | Keep the wallet funded — off-session refill when balance drops below a threshold, capped monthly |
+| `myapi account sending` / `myapi account resume-sending` | Is sending paused (bounces), and turn it on |
 | `myapi account mailing-address ["<address>"]` | Get or set the account's CAN-SPAM mailing address (required for email send) |
 | `myapi config set-org <id>` / `set-funnel <id>` / `set-domain <name>` | Set CLI defaults |
 | `myapi install-skills` | Install agent skills into ~/.claude/, ~/.gemini/, ~/.cursor/ |

package/dist/skills/my-email-api/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-email-api
-version: 1.0.1
+version: 1.1.0
 description: >
   Send transactional and bulk email from your own domain. Create mailboxes, send/receive messages, generate AI templates, and manage warmup.
 triggers: [email, mailbox, send email, transactional email, template, warmup, inbox, outbox, ses, sender reputation]
-checksum: sha256-18f539fc12dd9e9e8f2abecf518aa1ee70741f85cc26ba0a6a941b9c29d537d8
+checksum: sha256-17c2dfb50676262f2fe38688f5e7d9cfce3504354c17c06c3dd1dd1b8e39fa5e
 ---
 
 # MyEmailAPI
@@ -28,6 +28,7 @@ A registered domain via **mydomainapi** is the prerequisite — mailboxes need a
 | `email message` | `send`, `status`, `sent`, `inbox`, `outbox`, `get` | Transactional send + read |
 | `email warmup` | `start`, `stats`, `pause`, `resume`, `stop` | IP/domain warmup for sending reputation |
 | `email template` | `generate`, `list`, `get`, `preview`, `edit`, `send-test`, `delete` | AI-generated HTML templates |
+| `email campaign` | `create`, `list`, `get`, `update`, `resolve`, `start`, `pause`, `resume`, `cancel`, `recipients`, `stats` | Scheduled bulk send that drains at a daily limit |
 <!-- generated:end -->
 
 ## Examples
@@ -72,10 +73,54 @@ myapi email warmup stats --address hello@yourdomain.com
 | `--per-day` | `warmup start` | Cap the daily volume the ramp climbs to |
 | `--emails`, `--quick` | `verify bulk` | Addresses inline rather than on stdin; skip the catch-all probe |
 
+| `--addresses <csv>` | `campaign create` | An explicit short recipient list |
+| `--crm-stage`, `--crm-origin`, `--crm-company` | `campaign create` | Draw recipients from CRM instead |
+| `--crm-max-days`, `--crm-min-days` | `campaign create` | Engaged more than / within N days ago |
+| `--all-contacts` | `campaign create` | Every CRM contact — the unfiltered query, asked for by name |
+| `--state` | `campaign recipients` | Filter by `queued`, `sent`, `failed` or `excluded` |
+
 Forwarding keeps the original: `set-forwarding <user@domain> <forward-to@domain>`
 copies every inbound message to an external address and leaves it in the mailbox.
 `clear-forwarding <user@domain>` stops it.
 
+## Campaigns — a scheduled send, not a bulk one
+
+A campaign is scheduling on top of `message send`. It picks a **source**, freezes
+it, then drains at a daily limit.
+
+```bash
+# Draw from CRM: qualified contacts not engaged in 30+ days
+myapi email campaign create --name "Q3 re-engage" \
+  --template <template-id> --from you@yourdomain.com \
+  --crm-stage qualified --crm-max-days 30
+
+myapi email campaign resolve <id>   # who it reaches + what it costs. SENDS NOTHING.
+myapi email campaign start <id>     # begins; consent to the cost
+myapi email campaign stats <id>     # counts by state, sent today, daily limit
+```
+
+Four things that decide how you use it:
+
+- **`resolve` before `start`, always.** Resolve freezes the recipient set and
+  reports the count and the estimated cost without sending. It is the only way
+  to see what a start commits to, and `start` refuses an unresolved campaign.
+- **It does NOT send all at once.** A campaign spends `per_day_limit` per day,
+  spread across the day, and continues tomorrow. A campaign still `active` the
+  next morning is working, not stuck — bursting a list is the surest way to get
+  an account's sending paused.
+- **Recipients come from a source, not an upload.** `--crm-*` filters CRM
+  contacts (and sends land on their timeline); `--addresses` is for a short
+  ad-hoc list. There is no file upload: import into CRM first, and suppression,
+  unsubscribes and history then apply to those people like everyone else.
+- **Exclusions are reported, not hidden.** Resolve returns counts by reason —
+  suppressed, duplicate, invalid — so a set smaller than the source is
+  explainable. Suppression is checked AGAIN at send time, so someone who
+  unsubscribes mid-campaign is dropped rather than mailed.
+
+`pause` stops after the message in flight; `resume` continues; `cancel` ends it
+and drops what was queued. Status `paused_insufficient_funds` means the account
+could not pay — top up or enable auto-recharge, then `resume`.
+
 ## Notes
 
 - A mailbox is uniquely identified by its address (`username@domain`).
@@ -111,6 +156,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Account-scoped, not org-scoped** — no `{org_id}` segment; the key identifies the account.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi email --help` or `myapi email <namespace> --help` for full flag reference.

package/dist/skills/my-email-verify-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.0
 description: >
   Synchronous single-address email verification — syntax + DNS + Microsoft GetCredentialType probe. Returns a verdict in <1s for ~50% of inputs; the rest get verdict='unknown' with smtp_recommended=true. The pre-send quality gate for any outbound campaign.
 triggers: [email verify, email validation, deliverability, smtp, syntax check, dns mx, microsoft, mx lookup, bounce prevention]
-checksum: sha256-c8ae836c355066eee8a12753f818d3a90c35b99983d74913c8fc76edcc99668f
+checksum: sha256-0a654a6674bb40863d9bbffb3e6862e10f7e7603695e995416779f0a6b312865
 ---
 
 # MyEmailVerifyAPI
@@ -103,6 +103,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi email verify --help` for inline reference.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.21.0",
+  "version": "2.22.0",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.21.0"
+    "@myapihq/sdk": "^2.22.0"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",