# agent-cold-email MCP server

Agent-run cold-email infra: 24 MCP tools, live sending, free sandbox. $99/mo, concierge go-live.

## Links
- Registry page: https://www.getdrio.com/mcp/io-github-ys-projectcalc-agent-cold-email
- Repository: https://github.com/YS-projectcalc/agent-cold-email
- Website: https://coldrig.dev/

## Install
- Command: `npx -y agent-cold-email`
- Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- Auth: Auth required by registry metadata

## Setup notes
- Remote header: Authorization (required; secret)
- Package: Npm agent-cold-email v0.2.0
- Environment variable: AGENT_COLD_EMAIL_API_KEY (secret)
- Environment variable: AGENT_COLD_EMAIL_BASE_URL
- The upstream registry signals required auth or secrets.
- Remote endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- Header: Authorization

## Tools
- setup_infrastructure - Provision sending infrastructure: buy branded lookalike domains, create mailboxes, start warmup. New mailboxes are ramp-limited server-side — 5 sends/day in week 1, rising to 40/day after 4 weeks — and your own calls cannot exceed that cap; poll infrastructure_status for the current dailyCap. Inputs: brand, primaryDomain, domains + inboxesEach counts, persona, physicalAddress, senderIdentity. Billing is per-provisioned-mailbox ($10/mailbox + $49 platform, min 5) and the billed quantity follows what you provision here — pass quoteOnly:true first to preview the new count + projected monthly price before committing (no silent capacity addition). Every response carries a `billing` projection { provisionedAfter (the live count AFTER this call — reality, not the ask), projectedMonthlyCents, formula }: on quoteOnly it's the preview, on an actual provision it's the real post-provision bill (a capacity-limited partial reflects only what landed). Async — returns { jobId, billing }; poll infrastructure_status for progress. Resend the same idempotencyKey on retry to avoid double-provisioning. `registerDomains` (default false) is this tenant's opt-in consent to real domain purchases made on the platform's own account (our COGS — your bill is unchanged, mailbox-count-based only); leave it false/omitted unless you intend real domain spend, and only the operator's own global switch being armed too can ever actually enable it. When `registerDomains` is true, `registrant` is REQUIRED: a full registrant-of-record object { firstName, lastName, email, phone, addressLine1, city, state, country, postalCode, organization (optional, defaults to brand) } — this platform never invents a domain registrant's legal identity, so omitting it rejects the call at the boundary naming the missing fields. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- infrastructure_status - Warmup + provisioning progress per mailbox. New mailboxes are ramp-limited server-side: 5 sends/day week 1 rising to 40/day after 4 weeks; current dailyCap for each mailbox is in the response below. Returns { domains, mailboxes, sendReady, mailboxHealth[] }; each mailbox: warmupDay, dailyCap, sentToday, sendReady, delivStatus (healthy/throttled/paused), complaint/bounce/softBounce rates (first-party measured), vendorReputationScore + vendorPlacementRate (VENDOR-REPORTED approximations, not first-party measurements — the control loop uses local signals only), lastPolledAt. Use account/metrics for account-wide rollups. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- launch_campaign - Create and activate a campaign on a lead list. You supply name, offer, leads[], sequence[] (per step: subject, body, delayDays), sendWindow, timezone, stopOnReply — the platform does not write copy. Steps schedule up front; suppressed leads are skipped. Returns { campaignId }. Resend the same idempotencyKey on retry to avoid a duplicate. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- campaign_results - Outcome counts for ONE campaign. Input: campaignId (from launch_campaign). Returns { campaignId, sent, reply, bounce, complaint, unsubscribe, failed, soft_bounce } — bounce = HARD only, soft_bounce separate, opens not tracked. 404 if unknown. Use metrics for account-wide totals, list_campaigns for every campaign at once. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- metrics - Account-wide outcome totals across ALL campaigns: { sent, reply, bounce, complaint, unsubscribe, failed, soft_bounce } — same shape as campaign_results but summed tenant-wide (bounce = hard only, opens not tracked). Use campaign_results for one campaign, list_campaigns per-campaign, or account for billing/quota. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- inbox - Unified reply inbox across mailboxes. Cursor-paginated → { threads[], nextCursor }; each row: threadId, campaignName, leadEmail, subject, mailboxEmail, label, lastEventType, markStatus. Filters: mailbox, campaign, label, read, includeNonreply (bounces/OOO, default true), archived (exclude|include|only). Use thread for one thread's history. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- thread - Full message history for ONE thread. Input: threadId (from inbox). Returns { threadId, campaignId, leadId, leadEmail, mailboxEmail (null before first send), messages[] }, each message { type (sent/reply/bounce/...), ts, messageId, metadata }, oldest first. 404 if unknown. Use inbox to LIST threads; reply to respond; mark/label_thread to triage. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- reply - Send a reply on an existing thread, from the mailbox that sent it. Inputs: threadId, body. Returns { messageId }. A reply is real sending volume and is governed exactly like campaign sends: it counts against that mailbox's daily cap (sentToday +1, visible in infrastructure_status), and it is REFUSED — never silently dropped — when the recipient is suppressed, the mailbox is deliverability-paused, or the cap is used up. A refusal returns { error, code:'send_blocked', reason:'suppressed'|'mailbox_paused'|'daily_cap_reached', retryable }: retryable (cap) clears at the next daily rollover, non-retryable does not, so stop retrying and don't loop replies to manufacture volume. Idempotent: identical retries collapse to one send — pass a stable idempotencyKey (else a body hash is used) so a dropped-response retry can't double-send. 404 if no sending mailbox is on record for the thread. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- mark - Set a thread's READ-STATE for inbox triage. Inputs: threadId, status = 'read' | 'unread' | 'archived' (archived hides it from the default inbox; refetch with inbox archived='include'/'only'). Returns { marked: true }. 404 if unknown. This is the read/archive flag ONLY — use label_thread for a triage label chip, reply to respond. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- pause - Pause ONE campaign: its status → 'paused', so the tick schedules no further steps (already-sent mail is unaffected; there is no resume tool). Input: campaignId. Returns { paused: true }. 404 if not found. Use pause_all to pause every active campaign at once. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- pause_all - Pause EVERY active campaign for the tenant at once (each active status → 'paused'; the tick then schedules no further sends). No inputs. Returns { pausedAll: true }. Use pause to pause a single campaign by id. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- account - Account overview: brand, plan, status, billingState, activationState, resource counts, usageCents, quota, deliverability (loop state: paused/throttled mailboxes, burning domains, auto-replacements, recentActions[]), and teardown (reclaim summary once canceled, else null). Billing is per-provisioned-mailbox: $49 platform + $10 x live provisioned mailboxes, minimum 5 ($99); the billed quantity tracks the real provisioned count (deprovision lowers it). activationState is the HONEST send state — trust it over 'sent' counts: 'active' = real sending live; 'pending_provisioning' = paid but infrastructure still being armed, sends shown are sandbox previews that DON'T leave; 'capacity_pending' = provisioning held at a spend/plan-slot limit; 'screening_hold' = account under review; 'sandbox' = demo/free. Use metrics for counts, infrastructure_status for per-mailbox health. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- remove_mailboxes - Downgrade: release your N NEWEST live mailboxes now and lower the billed quantity. Inputs: count, acknowledged (must be true — this is a quoted, irreversible-this-cycle consent: the release is immediate for provisioning but there is NO mid-cycle credit; the lower price takes effect next renewal, minimum 5 mailboxes / $99). Returns { releasedCount, quote } where quote is the new projected monthly. To ADD mailboxes use setup_infrastructure / configure_byo_domain (request_managed_mailboxes). Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- get_dashboard - Read saved dashboard views. No id → list all: [{ id, name, isDefault, rev, editedBy }]. With id → that view's full layout + rev (pass this rev as the CAS base to configure_dashboard update). Views are both agent- and human-editable; write them with configure_dashboard. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- configure_dashboard - Write a saved dashboard view. action = create (needs name+layout) | update (needs id+rev+layout; optional name renames) | promote (id → default) | delete (id). update is rev-CAS: a stale rev returns { currentRev, currentLayout } to rebase and retry. Optional note. Read the current rev+layout via get_dashboard first. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- label_thread - Set or clear a triage LABEL on an inbox thread — the same chip the dashboard shows. Inputs: threadId, label (string; pass label:null to clear). Distinct from mark (read/unread/archived state): a label is a free-form category, not a read flag. Filterable via inbox's label param. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- list_campaigns - List every campaign at once: [{ campaignId, name, status, counts{sent,reply,bounce,complaint,unsubscribe,failed,soft_bounce} }], newest first — no per-campaign lookup needed. Use campaign_results for one campaign's counts, metrics for account-wide totals. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- activity - Unified activity feed: campaign events (sent/reply/bounce/...) merged with deliverability loop actions (pause/throttle/replace-domain). Cursor-paginated → { items[], nextCursor }; each item { id, kind:'event'|'deliverability', label, ts, target, detail }. Filters: kind, limit (default 50, max 200). Use inbox for replies only. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- get_webhooks - List your outbound webhook subscriptions, or (with id) one subscription plus its recent delivery + attempt log. No id → [{ id, url, eventTypes, active, status, disabledReason, consecutiveFailures }]. With id → { subscription, recentDeliveries[], recentAttempts[] }. Secrets are never returned on reads — they are shown once at create/rotate. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- configure_webhook - Manage an outbound webhook subscription. action = create (needs url + eventTypes: reply|bounce|soft_bounce|complaint; optional secret/active) | update (needs id + one changed field; active:true re-enables an auto-disabled one, active:false pauses; secret rotates) | delete (needs id). create/rotate return the HMAC signing secret ONCE. URLs must be https to a public host (private/metadata IPs rejected). Deliveries are signed X-Coldrig-Signature: sha256=HMAC-SHA256(secret, raw body). Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- get_byo_domains - List your BYO (bring-your-own) domains, or (with id) one domain's full intake detail. No id → [{ domainId, domain, isPrimary, dnsMode, byoStatus, breakerTier, reputationBranch, mailboxCount }]. With id → adds the pre-flight scan result, abuse-gate verdict, and consent-acknowledgment status. byoStatus progresses pending_kyc|pending_consent|pending_dns → active (or rejected/abandoned). Use configure_byo_domain to register a new one or advance it. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- configure_byo_domain - Register or advance a BYO domain/mailbox intake (SPEC.md §20). action = register (needs domain + domainRelationship: fresh_standalone|subdomain_of_primary|is_primary — runs the pre-flight live-infra scan + abuse gate + reputation ladder, returns the starting byoStatus) | poll_dns (needs id — re-checks DNS delegation/records, advances pending_dns → active, or → abandoned after 7 idle days) | acknowledge_consent (needs id + acknowledged:true — REQUIRED before a primary domain can proceed past pending_consent; this does not remove your business's exposure, it documents informed consent) | request_managed_mailboxes (needs id + count — platform-provisioned mailboxes on an ALREADY-ACTIVE domain, the primary shape; every response carries a `billing` projection { provisionedAfter, projectedMonthlyCents, formula } — quoteOnly:true previews it without provisioning) | connect_mailbox (needs id + email + transport — declares an EXISTING OAuth/SMTP+IMAP connection you already have, bypassing provisioning; transport is { kind:'smtp', host, port, secure, user, pass } | { kind:'gmail_api', clientId, clientSecret, refreshToken } | { kind:'ms_graph', mode, tenantId, clientId, clientSecret, refreshToken? }). Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- suppress_lead - Permanently suppress an email address tenant-wide (every current and future campaign) — the manual/free-text 'stop emailing me' path for opt-outs the strict typed-unsubscribe matcher misses. Inputs: email, reason (fixed 'manual' — the only value this tool honestly claims; bounce/complaint/unsubscribe are recorded automatically elsewhere), note (accepted, not persisted). Cancels every pending send + marks every campaign-lead row 'suppressed'. Last-write-wins: re-suppressing a bounce/complaint/unsubscribe row relabels its reason to 'manual'. There is no un-suppress tool. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- update_lead - Record what you learned about a contact (their reply, your triage) as a durable, contact-level disposition — keyed by email, visible across every campaign that lists them. Inputs: email, interestStatus (none|interested|meeting_booked|not_now|not_interested|bad_fit|out_of_office|wrong_person — a server-enforced enum; 'do not contact' is NOT a member, use suppress_lead instead), notes, tags (free-form). A PARTIAL patch — only the fields you pass are changed; at least one of interestStatus/notes/tags is required. Filterable via list_leads. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp
- list_leads - List/export leads with their contact-level disposition, cursor-paginated. Returns { leads[], nextCursor }; each row: leadId, email, firstName, company, campaignId, campaignName, globalStatus, interestStatus, notes, tags, suppressed, lastEventType, lastEventTs, createdAt. Filters: campaign, interestStatus, suppressed, replied. This IS the export surface — paginate to dump the full book of business as JSON (no separate CSV endpoint). Use update_lead to write disposition, suppress_lead to opt an address out. Endpoint: https://agent-cold-email-api.yaakovscher.workers.dev/mcp

## Resources
Not captured

## Prompts
Not captured

## Metadata
- Owner: io.github.YS-projectcalc
- Version: 0.2.2
- Runtime: Npm
- Transports: STDIO, HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: Jul 22, 2026
- Source: https://registry.modelcontextprotocol.io