API Reference

Get a high-level overview of the account: counts of agents, prospects, lists, products and mailboxes, plus the daily email limit.

curl https://coldpegion.com/api/v1/overview \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Get the user's company profile.

curl https://coldpegion.com/api/v1/company \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Create or update the company profile fields.

curl -X PATCH https://coldpegion.com/api/v1/company \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"companyName":"…","industry":"…"}'

Set the global daily email limit (safety cap across all agents).

curl -X PATCH https://coldpegion.com/api/v1/settings/daily-limit \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":10}'

Create a draft campaign from a brief with its offer and audience automatically. Does not send. Choose reviewMode: COLDPEGION (default, user approves in app), MCP_CLIENT (ask user in this client before approval), or AUTO (no review). Reuse requestId on retries. Then import contacts, configure_agent with senderEmails, set_agent_sequence or prepare_emails, review as required, and launch_agent.

curl -X POST https://coldpegion.com/api/v1/campaigns \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"requestId":"…","brief":"…"}'

Page through this campaign's contacts to write individually personalized emails. Use only supplied facts. DNC contacts must not be contacted. Cursor is the last returned prospect id.

curl https://coldpegion.com/api/v1/agents/{agent}/contacts \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Read exact per-recipient messages, revisions, reviewEpoch and approval states. In MCP_CLIENT mode show these to the user and ask approval before approve_campaign_emails. In COLDPEGION mode send the user to reviewUrl. Pagination must be respected; never approve unseen pages.

curl https://coldpegion.com/api/v1/agents/{agent}/review \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Materialize a small batch of exact per-person messages for review from a static/AI campaign. Built-in AI usage is charged for generated messages. For EXTERNAL campaigns write each person's message yourself with prepare_emails instead. Repeat while remaining > 0, then get_campaign_review.

curl -X POST https://coldpegion.com/api/v1/agents/{agent}/review/prepare \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

List AI agents with status and how many emails each has sent.

curl https://coldpegion.com/api/v1/agents \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Create an AI outreach agent, wiring up products, a target list, sender mailbox(es) and guidelines. Does NOT launch it.

curl -X POST https://coldpegion.com/api/v1/agents \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","listName":"…"}'

Update an agent's sending cadence, daily limit, schedule, guidelines or sequence mode.

curl -X PATCH https://coldpegion.com/api/v1/agents/{agent} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"guidelines":"…","sequenceMode":"AI_GENERATED"}'

Launch a campaign. MCP_CLIENT requires user-confirmed approval of exact email revisions first. COLDPEGION requires approval in the app. AUTO needs no review. Normal sender, suppression and schedule checks always apply.

curl -X POST https://coldpegion.com/api/v1/agents/{agent}/launch \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Pause an agent so it stops sending.

curl -X POST https://coldpegion.com/api/v1/agents/{agent}/pause \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Duplicate an existing agent's configuration as a new DRAFT.

curl -X POST https://coldpegion.com/api/v1/agents/{agent}/clone \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Set an agent's static multi-step sequence (subject/body templates with {{firstName}}, {{companyName}}, {{jobTitle}} variables). Bodies accept plain text or safe HTML fragments (p, strong, em, ul/li, a). Unsafe HTML is removed at delivery. No platform LLM is used. Pause before changing content; earlier approvals are invalidated.

curl -X PUT https://coldpegion.com/api/v1/agents/{agent}/sequence \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"steps":[{}]}'

Bulk-push pre-written, per-lead emails for an agent (one unique email per prospect). Bodies accept plain text or safe HTML fragments (p, strong, em, ul/li, a). The worker sanitizes HTML and sends with NO platform LLM call — AI marketing at scale, paid by your own Claude. Up to 500 items/call; paginate for more. Switches the agent to EXTERNAL mode by default.

curl -X POST https://coldpegion.com/api/v1/agents/{agent}/prepared-emails \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"items":[{}]}'

Use AI to write campaign guidelines and/or a multi-step email sequence, then optionally save them onto an agent.

curl -X POST https://coldpegion.com/api/v1/authoring/campaign-content \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"what":"guidelines","productNames":["…"]}'

Verify an address using the user's selected verifier: ZeroBounce or BillionVerify with their saved key, otherwise built-in checks. May consume their provider credits. UNKNOWN means mailbox existence was not established; never describe it as valid. Results update an owned prospect if present. No email is sent.

curl -X POST https://coldpegion.com/api/v1/verification/email \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'

List prospect lists with their prospect counts.

curl https://coldpegion.com/api/v1/prospect-lists \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Create a new (empty) prospect list.

curl -X POST https://coldpegion.com/api/v1/prospect-lists \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

Add a single prospect to a list (creates/updates the prospect).

curl -X POST https://coldpegion.com/api/v1/prospects \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listName":"…","email":"…"}'

Bulk-import leads into a list (creates the list if it doesn't exist). Use this to push leads you mined from other connectors. Up to 500 per call — paginate for more.

curl -X POST https://coldpegion.com/api/v1/prospects/import \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listName":"…","leads":[{}]}'

Search for leads (Instantly/Apollo-style) by filters, in the shared lead database, the user's prospects, or Apollo (if configured). Optionally import the results into a list.

curl -X POST https://coldpegion.com/api/v1/leads/search \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jobTitles":["…"],"seniorities":["…"]}'

Add or remove a prospect from the do-not-contact (DNC) list by email. DNC prospects are skipped by all campaigns.

curl -X PUT https://coldpegion.com/api/v1/prospects/do-not-contact \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'

Add email addresses or whole domains (e.g. 'acme.com') to the global suppression list. Suppressed addresses are NEVER emailed by any campaign, even if imported as prospects later — use for compliance opt-outs, customers, competitors.

curl -X POST https://coldpegion.com/api/v1/suppressions \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"values":["…"]}'

List the user's products with their ICP.

curl https://coldpegion.com/api/v1/products \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Create a new product the agents can market. Optionally include an ICP description.

curl -X POST https://coldpegion.com/api/v1/products \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…"}'

Update an existing product by id or name.

curl -X PATCH https://coldpegion.com/api/v1/products/{product} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"…","description":"…"}'

Delete a product. Destructive — only call with confirm:true after the user explicitly confirms.

curl -X DELETE https://coldpegion.com/api/v1/products/{product} \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

List the mailboxes available to the user (owned, assigned, or shared by the org), with provider and daily usage.

curl https://coldpegion.com/api/v1/email-accounts \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Get per-domain and per-mailbox deliverability stats (sent, reply rate, bounce rate, today's utilization) to decide which mailbox/domain to send from. Pro plan module.

curl https://coldpegion.com/api/v1/deliverability \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Get the most recent inbound replies with their AI category (INTERESTED, NOT_INTERESTED, etc.).

curl https://coldpegion.com/api/v1/inbox/replies \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Pull new inbound mail over IMAP for the user's mailboxes and detect replies now.

curl -X POST https://coldpegion.com/api/v1/inbox/sync \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

List organization members (with roles) and any pending join requests.

curl https://coldpegion.com/api/v1/team \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Invite a teammate to the organization by email (admins only).

curl -X POST https://coldpegion.com/api/v1/team/invites \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'

Approve or deny a pending join request by the requester's email (admins only).

curl -X POST https://coldpegion.com/api/v1/team/join-requests \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'

Change an organization member's role (admins only; only an owner can grant OWNER).

curl -X PATCH https://coldpegion.com/api/v1/team/members \
  -H "Authorization: Bearer $COLDPEGION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…","role":"OWNER"}'

List all ColdPegion help guides (slug, title, description, category). Use this to discover which guide answers a how-to or product question.

curl https://coldpegion.com/api/v1/help/topics \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"

Get the full content of a ColdPegion help guide. Pass an exact slug (from list_help_topics) or a free-text question (e.g. 'how do I connect gmail') and the best-matching guides are returned as markdown. ALWAYS use this to answer how-to, setup, billing, deliverability, or troubleshooting questions instead of guessing.

curl https://coldpegion.com/api/v1/help/guides \
  -H "Authorization: Bearer $COLDPEGION_API_KEY"